Publish manual as a website

[nawordar]

I'm just trying SILE and I stumbled upon the same problem as with TeX, LuaTeX, ConTeXt etc. — the documentation is only available as PDF which is not easily searchable. I understand that PDF allows to show off the typesetter capabilities, but it's just not very practical for software documentation. I see that SILE supports creating custom outputters, so maybe an HTML outputter could be created for that?

Related issue: #1337 (leet!) — this one is for developer documentation, but I think that manual could benefit from being available as a website too.

[alerque]

We've certainly considered this and from time to time it still crosses my mind, but there is a huge problem with the idea: the developer docs with Lua APIs are a little bit different, but as far as end user facing document commands and classes go the thing we are documenting is specifically designed for output to PDF / print. Having the documentation in PDF allows the techniques to de demonstrated inline. The alternative would be we need to generate HTML or some other markup and also generate a million illustration images that are snippets of PDF's converted to images so the examples can be seen. Even at that the result would not be nearly as informative as seeing the changes inline in the PDF.

It's not off the table entirely, but even if we were to write up a new outputter which mimicked the PDF output in some other markup environment, the results would inevitably be different and lead to confusion.

[nawordar]

You're right, this is more complicated than I thought. I've just started learning SILE and I haven't read the whole manual yet, so maybe I created this issue too soon.

Maybe the ConTeXt approach isn't that bad: have a wiki for quick information and a PDF for more in-depth knowledge? I see that there is already wiki enabled on this repository, but it mentions that it's aimed at developers

[nawordar]

I've just learned that TikZ has an unofficial HTML documentation at https://tikz.dev. It is converted from LaTeX using lwarp. I haven't yet looked at how that package works, but the results look really good. Just saving it for the future reference, so maybe I will look into it later.

[hegjon]

Not sure if if it is possible to convert the PDF into a input format that Pandoc supports? https://pandoc.org/MANUAL.html#general-options

Specify input format. FORMAT can be:

• bibtex (BibTeX bibliography)
• biblatex (BibLaTeX bibliography)
• bits (BITS XML, alias for jats)
• commonmark (CommonMark Markdown)
• commonmark_x (CommonMark Markdown with extensions)
• creole (Creole 1.0)
• csljson (CSL JSON bibliography)
• csv (CSV table)
• tsv (TSV table)
• docbook (DocBook)
• docx (Word docx)
• dokuwiki (DokuWiki markup)
• endnotexml (EndNote XML bibliography)
• epub (EPUB)
• fb2 (FictionBook2 e-book)
• gfm (GitHub-Flavored Markdown), or the deprecated and less accurate markdown_github; use markdown_github only if you need extensions not supported in gfm.
• haddock (Haddock markup)
• html (HTML)
• ipynb (Jupyter notebook)
• jats (JATS XML)
• jira (Jira/Confluence wiki markup)
• json (JSON version of native AST)
• latex (LaTeX)
• markdown (Pandoc’s Markdown)
• markdown_mmd (MultiMarkdown)
• markdown_phpextra (PHP Markdown Extra)
• markdown_strict (original unextended Markdown)
• mediawiki (MediaWiki markup)
• man (roff man)
• muse (Muse)
• native (native Haskell)
• odt (ODT)
• opml (OPML)
• org (Emacs Org mode)
• ris (RIS bibliography)
• rtf (Rich Text Format)
• rst (reStructuredText)
• t2t (txt2tags)
• textile (Textile)
• tikiwiki (TikiWiki markup)
• twiki (TWiki markup)
• typst (typst)
• vimwiki (Vimwiki)
• the path of a custom Lua reader, see Custom readers and writers below

[Omikhleia]

@hegjon

Not sure if if it is possible to convert the PDF into a input format that Pandoc supports

No, not really, because (as @alerque actually mentions above), the current manual in many places demonstrates things that result from processing, and would lose that in the conversion process from the source.

As mentioned, an HTML outputter could be created (I have a raw experimental one actually -- but there would be a lot more things needed to make it useful)...

Or, of couse, one could make a subset of the documentation without the actual demonstrations...

[alerque]

As @Omikheia says..

On the flip side, we can use code snippets to generate images to embed the demonstration output into a web version of the docs.

Any such attempt to retool should come after the more approachable step of generating API docs for Lua and Rust APIs. These would be much more technical and coding oriented (the expected arguments and variables) than design oriented and would be much easier to present in a web format while still keeping the "Manual" in a typeset format that much more readily demonstrates concepts instead of just talking about them.

[hegjon]

No, not really, because (as @alerque actually mentions above), the current manual in many places demonstrates things that result from processing, and would lose that in the conversion process from the source.

I discovered the same when playing around with converting the manual.