Writing a User Manual

[bearbin]

Each page could not contain it's own title tag because one document could not contain more than one. You would just have to get it from the filename or something.

[xoft]

I was thinking that the entire "book" would be split into chapters, each chapter in a separate HTML file. Each HTML file would be a well-formatted full-fledged HTML, with the header and everything. Then there could be an optional external tool that would take these files, generate a TOC HTML file for them, and optionally one huge HTML file with the contents of each file's body.

Am I overcomplicating things?

[bearbin]

The only problem is that if you want to change the header, you have to go and change 20+ files to change the header. And if you're changing the header 10 times a day, that's going to get annoying.

[worktycho]

A templating system would fix that. If we use github pages jekyll is the obvious choice.

[bearbin]

We would not be using GitHub Pages.

[xoft]

And why not?

[bearbin]

What I really should have said is that I don't think jekyll is a good idea - especially if we want to generate one megafile with all the sections in it.

[worktycho]

Jekyll can handle that, just have a file that includes all the sections. If you don't want to use jekyll can I recommend Template Toolkit Available in perl and python versions; or handlebars.

[bearbin]

I've used basic python templates before and they worked perfectly fine. I'll see about getting a basic generator up in Lua or python, it shouldn't take too long.

[worktycho]

I've tried writing a template engine before. It is seriously worth using the existing template engine as they provide loads of extra features.