First pass at documentation

[pkgw]

The Tectonic documentation tool, ironically, has no documentation itself. That needs to be fixed.

One day the docs will be written in TeX, but for the proximate future I think it is more practical to write them in Markdown so that they can appear on the website — with Unicode and decent CSS, the presentation will be sufficiently readable. Translating from MD to TeX will require some effort in the future, but it will just be a bit of busywork, not anything fundamentally challenging.

• the config file (cc Support HTTP proxies #59)
• the command line options
• the idea behind the "bundle" approach
• what to do if a needed file is missing or too old
• (lack of) biblatex/biber support
• location and structure of cache directory (cc Document the location and structure of the cache directory #45)
• "why not just use latemk?" etc
• emphasize that Tectonic is its own engine, not something that runs other engines
• how to emulate latexmk -pvc (cf Continuous mode #82 and other issues)

[iandol]

translating from MD to LaTeX will require some effort in the future

Why not use the awesome pandoc to translate to LaTeX? It has excellent support for custom latex templates and raw latex. You can build latex, epub and HTML pages from the same markdown source. It seems perfect for this task.

[robbystk]

How should this be organized? I think some of these need dedicated pages (config, command options), and the rest could be in a single FAQ page. The FAQ should probably be linked in the header, but I'm not sure if there's room for three more things (command options, configuration, FAQ). Perhaps a 'getting started' page could be added that would then link to installation, commands, configuration, and the FAQ.

[robbystk]

I guess I should just make pages and ask questions later.

[pkgw]

@iandol Well, no lack of love for pandoc here, but one of the goals of Tectonic is to hopefully make it so that TeX can be an attractive source language for technical documentation that targets modern output formats. If we can't eat our own dogfood ...

But, it's true that right now we can't eat our own dogfood since HTML really is necessary and I haven't written that part of Tectonic yet. So, Markdown for now.

[pkgw]

@robbystk Contributions are definitely welcome! I want to sit down and plan out both the technical implementation and the organization for the first-cut user docs, but I'm pretty sure that anything delivered as a Markdown file will be useful regardless of the final decisions on that front.

One technical issue is that I think we really want the documentation of the program to live in this repo, but then it needs to make it into the website repo to make it to the web. I guess I can just do the same thing I do for the API docs right now ... it's not like we want the docs on the website to track master anyway.

It would also be nice to serve multiple versions of the docs as the tool evolves ... can we (ab)use ReadTheDocs.org somehow?

[pkgw]

Also, I've been thinking that the main sections of the website should be Tectonic (i.e. the main landing page), Install, Learn, and Contribute.

[pciavald]

hey @pkgw, reading this conversation i noted that

one of the goals of Tectonic is to hopefully make it so that TeX can be an attractive source language for technical documentation that targets modern output formats

I cannot agree with this goal more. However, our dogfood is not as attractive as MD can be, hence the category of people who work with our dogfood, hence the poor UI problem inherent to TeX.

I've recently started using pandoc+texlive+atom(+jekyll) to write my documentation, specs, articles... and I find that creating most of the content in MD and using TeX and HTML only where MD falls short is extremely readable and convenient.

This message is to attest my gratitude in building the future of TeX and I hope to someday be able to use pandoc with tectonic. I think there's no shame in writing most of the documentation of a modern, lightweight TeX engine in markdown :)

[pkgw]

@pciavald Thanks! I am all about being pragmatic and I think Markdown is going to be the pragmatic choice for a while. I do dream of a day where pure TeX can be competitive but we're definitely not there ... yet :-)

[PHPirates]

Voting to add documentation... and redirecting people to this issue to also vote for documentation...

[ghost]

Sounds like 2 main problems here:

1. knowing and finding the best approach to manage documentation
2. creating the content

I have had experience contributing to the Ember.js guides and they do a great job at making their guides documentation entirely contained within the repository. Given a JavaScript toolchain you can simply install and ember serve to see a locally served copy of the documentation.

We could consider authoring them in a format that crates.io can discover like csv does. As someone learning rust, I found it quite helpful to go through a tutorial directly from the official documentation. I couldn't find a livereload option, so a zola site embedded within this repository could be a short term workaround.

I think the answer to the first problem will require more specifications and laying out goals.
In the meantime I think we can solve problem 2. We should decide on preliminary directory structure in this repo and start writing the content in markdown.

[pkgw]

@efx I think I pretty much agree. I use zola for my personal website and am a big fan. That being said, other Rust projects seem to use mdBook ... but really it is high time to just get something going.

One of the reasons this issue has lingered for so long is that my bandwidth to work on Tectonic is very limited these days, but I am more than eager to encourage others to take the lead! (Well, there is definitely a controlling perfectionist part of me that wants to oversee every single character in the repo, but I try to fight that tendency.)

[ghost]

Sounds great!

Well, there is definitely a controlling perfectionist part of me that wants to oversee every single character in the repo, but I try to fight that tendency.

😆

I'll draft together a PR sometime this week with the basic structure.

[pkgw]

Update: with #444 I deployed a scheme to actually get our book stub posting to the live internet. Here's a forum post I wrote about it:

https://tectonic.newton.cx/t/ready-for-contributions-the-tectonic-book/199

and here's the link:

https://tectonic-typesetting.github.io/book/latest/