Hi Patrick,
Great! Thank you for continuing support of info for the documentation
along with the thorough explanation. This was my primary concern. The
thought of not having the GSL manual in Info for horrifying for me! So I
am indeed very relieved :-).
I completely understand and respect the reasons described. I just had
two comments about the second and fourth points.
Texinfo natively supports cross references (in-document links) within
its output PDFs. For example in Gnuastro's PDF manual:
https://www.gnu.org/software/gnuastro/manual/gnuastro.pdf
The page numbers in the short and full table of contents are links to
the respective page. Cross references are also possible within the text
of the manual, both internally and externally. For example in page one
of the manual above, under "Introduction", you can click on "Appendix C
[GNU Free Documentation License], page 265" and it will take you to the
respective page. In the next line, you can click on the URL and a
browser will open. If you are linking to other Texinfo generated PDFs
within the same directory, it will open the respective PDF and take you
to the proper section.
As far as I know this is the default behavior in Texinfo, for example
you can see links in these manuals also (among many others):
https://www.gnu.org/software/make/manual/make.pdf
https://www.gnu.org/software/gawk/manual/gawk.pdf
https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.pdf
Regarding actively development, Texinfo is also being actively
developed, it is just much more mature (has a more limited scope for
simplicity and portability). Its main developers are also acitve TeX
Live developers and frequently submit updates. The more frequent Texinfo
updates are committed to the GNU Portability Library (Gnulib) Git
repository.
I do understand that the choice has been made, I very much respect it.
The important thing for me is that the Info manuals will continue (thank
you for that). I just thought these comments were necessary for the
record/archives.
Thanks again for all the great work on GSL, Gnuastro would not have been
possible without it.
Cheers,
Mohammad
On 04/24/2017 08:23 PM, Patrick Alken wrote:
Hello Mohammad,
Thank you for the links - it is impressive what you've accomplished
with texinfo for your manual. I decided on sphinx for a few reasons:
1. Out of the box support for equations and images in HTML - I like what
you've done with texinfo on this front but still texinfo doesn't
natively support this without your modifications.
2. Modern PDF output - sphinx generates a linkable TOC and in-document
links which makes it easy to navigate the PDF output - texinfo doesn't
put any links in the PDF documents
3. The native source format for sphinx is much simpler and easier to
read than texinfo
4. Sphinx is currently being actively developed - I don't think texinfo
currently is
Also to answer your question, sphinx is able to produce info output, so
we will be providing info files with GSL - this is something many users
need so we made sure sphinx could do this before switching.
Patrick
On 04/24/2017 11:09 AM, Mohammad Akhlaghi 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/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
