6 ms·

For software and technical documentation, I recently rediscovered GNU Texinfo. It perfectly fills the gap that the others have left open. Consistent, fairly ea

For software and technical documentation, I recently rediscovered GNU Texinfo. It perfectly fills the gap that the others have left open. Consistent, fairly easy syntax, exports to DocBook, PDF, HTML and can be read interactively from terminal as well. In contrast to markdown|asciidoc|reStructuredText|… and LaTeX, it handles more complex, non-linear documentation very well. https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html https://www.gnu.org/software/texinfo/manual/texinfo/texinfo....

badsectoracula 5y ago
I wonder if Texinfo became a victim to naming that is easy to misunderstand. Based on many comments i've seen online, especially on Reddit, etc, whenever Texinfo is mentioned many people seem to read "info" which they then associate with the "GNU info" program and so they dismiss Texinfo as this weird documentation viewer that GNU insists on using instead of manpages - all of it being layers upon layers of misunderstandings that somehow (well, naming, i guess) persist. "Texinfo" is basically a structured document format, somewhat similar to DocBook, except instead of XML it uses a more compact and (IMO) easier to read and write syntax that @looks{ like this }. It is largely meant for full manuals, guides, etc. There are a bunch of conversion tools (AFAIK written in Perl) to convert Texinfo documents to other formats, like TeX, HTML and of course info. "info" is a hypertext document format, similar to CHM, though it predates it (and HTML) by many years. It is quite primitive though it has some neat indexing functionality which improves searching it (assuming good indices exist, but Texinfo has support for making those easily). One of its biggest issues is that it is a preformatted document and image support is "hacked in".. "GNU info" is GNU's viewer for info documents which uses some Emacs-like shortcuts which trips people. However there are other viewers like pinfo and tkinfo, the latter providing a lightweight graphical viewer and some help systems (e.g. KHelpCenter) also support viewing info files. AFAIK there is also a cgi-based viewer so one can also use their browser. On the other hand most viewers do not seem to support images. I'm not sure if i forgot any other use of "info" in there :-P
- Per_Bothner 5y ago
  There is a relatively new "js-info" option for viewing texinfo output. It is regular rich HTML along with some JavaScript for convenient navigation: a dynamic sidebar, a keyboard bindings (based on traditional info mode). To see it in action, check out the DomTerm home-page (https://domterm.org/index.html https://domterm.org/index.html), which is written in TexInfo with a little custom styling.
  - chungy 5y ago
    "js-info" is a name that's defeating attempts to search for it. Would you mind elaborating? Texinfo does seem like something in between (La)TeX and AsciiDoc in difficulty, while hypothetically being just as rich in markup as almost any need requires. I think it does suffer a bit from seeming outdated in present HTML outputs, but you do demonstrate that it doesn't need to be so.
    - Per_Bothner 5y ago
      "js-info" is just an informal name for something that isn't a separate distribution. It is part of the latest texinfo release (http://ftp.gnu.org/gnu/texinfo/ http://ftp.gnu.org/gnu/texinfo/ - currenty 6.8) as well as the git sources (https://git.savannah.gnu.org/cgit/texinfo.git https://git.savannah.gnu.org/cgit/texinfo.git). Specifically, what I call js-into is the "js" directory in the source code: info.js, modernizr.js, and info.css.
      - chungy 5y ago
        Thanks!

badsectoracula 5y ago

I wonder if Texinfo became a victim to naming that is easy to misunderstand. Based on many comments i've seen online, especially on Reddit, etc, whenever Texinfo is mentioned many people seem to read "info" which they then associate with the "GNU info" program and so they dismiss Texinfo as this weird documentation viewer that GNU insists on using instead of manpages - all of it being layers upon layers of misunderstandings that somehow (well, naming, i guess) persist. "Texinfo" is basically a structured document format, somewhat similar to DocBook, except instead of XML it uses a more compact and (IMO) easier to read and write syntax that @looks{ like this }. It is largely meant for full manuals, guides, etc. There are a bunch of conversion tools (AFAIK written in Perl) to convert Texinfo documents to other formats, like TeX, HTML and of course info. "info" is a hypertext document format, similar to CHM, though it predates it (and HTML) by many years. It is quite primitive though it has some neat indexing functionality which improves searching it (assuming good indices exist, but Texinfo has support for making those easily). One of its biggest issues is that it is a preformatted document and image support is "hacked in".. "GNU info" is GNU's viewer for info documents which uses some Emacs-like shortcuts which trips people. However there are other viewers like pinfo and tkinfo, the latter providing a lightweight graphical viewer and some help systems (e.g. KHelpCenter) also support viewing info files. AFAIK there is also a cgi-based viewer so one can also use their browser. On the other hand most viewers do not seem to support images. I'm not sure if i forgot any other use of "info" in there :-P

Per_Bothner 5y ago
There is a relatively new "js-info" option for viewing texinfo output. It is regular rich HTML along with some JavaScript for convenient navigation: a dynamic sidebar, a keyboard bindings (based on traditional info mode). To see it in action, check out the DomTerm home-page (https://domterm.org/index.html https://domterm.org/index.html), which is written in TexInfo with a little custom styling.
- chungy 5y ago
  "js-info" is a name that's defeating attempts to search for it. Would you mind elaborating? Texinfo does seem like something in between (La)TeX and AsciiDoc in difficulty, while hypothetically being just as rich in markup as almost any need requires. I think it does suffer a bit from seeming outdated in present HTML outputs, but you do demonstrate that it doesn't need to be so.
  - Per_Bothner 5y ago
    "js-info" is just an informal name for something that isn't a separate distribution. It is part of the latest texinfo release (http://ftp.gnu.org/gnu/texinfo/ http://ftp.gnu.org/gnu/texinfo/ - currenty 6.8) as well as the git sources (https://git.savannah.gnu.org/cgit/texinfo.git https://git.savannah.gnu.org/cgit/texinfo.git). Specifically, what I call js-into is the "js" directory in the source code: info.js, modernizr.js, and info.css.
    - chungy 5y ago
      Thanks!