Re: [Help-gsl] New documentation format

[Mohammad Akhlaghi]

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/Sampling-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