Re: [Help-gsl] New documentation format

[Liam Healy]

According to https://www.gnu.org/software/texinfo/, Sphinx can generate
texinfo output.
<http://sphinx.pocoo.org/latest/config.html#options-for-texinfo-output>

On Mon, Apr 24, 2017 at 12:09 PM, Mohammad Akhlaghi <
address@hidden> wrote:

> Dear Patrick,
>
> This is Mohammad Akhlaghi (maintainer of GNU Astronomy Utilities). We
> heavily rely on GSL in Gnuastro and I use it alot personally also. So I
> wanted to thank you for all the great work on this important package.
>
> I just wanted to see if future versions of GSL will also ship with the
> info documentation (in other words, is it possible to get an `info' output
> from Sphinx and make it installable in the GNU Build style)?
>
> The reason I am asking this is that I do all my development in Emacs and
> rely mostly on the great `info' documentations of the tools I use like GSL,
> GLIBC and many other programs/libraries (like Make and AWK also). Since
> info is offline, easily navigatable without having to move your hands to
> the touchpad or mouse, and can be used in the the non-GUI environment of
> the virtual console, it is a really attractive option. Also, since it is
> installed with the program on the system you can always be sure that your
> info documentation is the same version as the library/program, but for
> PDF/HTML, you need to check the version every time.
>
> The default HTML output of Texinfo is indeed not very attractive, I agree.
> Gnuastro's documentation also heavily uses mathematic equations and also
> comes with a library. To solve the appearence issues with the default HTML
> output of Texinfo, in Gnuastro, we have created this small shell script:
>
> http://git.savannah.gnu.org/cgit/gnuastro.git/tree/doc/forwebpage
>
> and these Texinfo macros to treat mathematical equations differently on
> different outputs:
>
> http://git.savannah.gnu.org/cgit/gnuastro.git/tree/doc/formath.texi
>
> A CSS class is also added and we also use MathJax (installed on the GNU
> servers) for displaying the equations. For example you can see some example
> pages with equations, figures and library function descrip tions in the
> links below.
>
> https://www.gnu.org/software/gnuastro/manual/html_node/Warping-basics.html
>
> https://www.gnu.org/software/gnuastro/manual/html_node/Sampl
> ing-theorem.html
>
> https://www.gnu.org/software/gnuastro/manual/html_node/World
> -Coordinate-System.html
>
> If Javascript is enabled, the equations display very nicely and the
> webpage viewer/user can also get the TeX/MathML source of the equations to
> use in their own documents for example (by right-clicking on the
> equations). MathJax is also configured to work with LibreJS.
>
> I understand that a lot of work has probably gone into the conversion to
> Sphinx, but just wanted point out how useful info can be and some solutions
> that exist for making better looking HTML webpages with Texinfo to benefit
> from both (CLI and GUI) worlds. If you would be willing to reconsider
> Texinfo, I would be happy/honored to help impelement these features.
>
> In any case, thank you very much for all the great work on GSL,
> Cheers,
> Mohammad
>
>
> On 04/24/2017 06:31 PM, Patrick Alken wrote:
>
>> Hello all,
>>
>>    Sometime ago it was suggested to switch the GSL documentation from the
>> current texinfo format to sphinx, which has superior HTML and PDF
>> rendering. I thought this was a good idea and so I have now converted the
>> GSL documentation over to sphinx, and a beta version is available at:
>>
>> https://www.gnu.org/software/gsl/doc/html/index.html
>>
>> I would appreciate if people could take a look at make any suggestions or
>> let me know if you spot any bugs. Perhaps everyone could read through their
>> favorite chapter and make sure the formulas and figures all look ok.
>>
>> Thanks,
>>
>> Patrick
>>
>>
>>
>