[James Ross]

Sid P., on 20 December 2015 - 06:48 AM, said:

I don't have extensive experience at creating larger .html documents, so I don't know the extent of the effort involved. What are the tools available? I have Expression Web 4.

I don't think we'd want to have people hand-editing HTML (with or without a WYSIWYG tool) as it would suffer from the same problem as copying and pasting things in to the Manual.doc file - formatting collisions and irregularities. But using something like Markdown or reStructuredText would be fine, and should allow generation of HTML and PDF forms. It would also allow the documentation to be put online easily e.g. at https://readthedocs.org/.

[Genma Saotome]

Actually you can save a .doc file as .hmtl as part of the save as function.

For myself, I dislike MS Word because (for one) I just don't think in terms of page formatting but paragraph formatting (the way Word Perfect worked). The method MS Word uses to handle the indent of structured documents just irks me whenever I need to do something slightly different. Obviously a minority opinion.

So I think I can suppress my dislike for it long enough to add another layer to the ToC. I have no suggestions to offer long term but it may prove that a .doc file works as well as anything else.

[gpz]

James Ross, on 20 December 2015 - 11:56 AM, said:

But using something like Markdown or reStructuredText would be fine

It sounds really interesting. I always hated to touch the MSWord format documentation. I haven't heard about ReStructuredText before, it is interesting to see what kind of things exist, I wouldn't even think of such a genuine way of handling documentation.

[gpz]

Just for fun, I converted the first 6 sections of the manual to reStructuredText. It was fast, since these sections are short ones, so they were good for experimenting. The result is quite pretty, and for me it is much more less disgusting to work with a manual in such a format than with Word.

I uploaded the result here, if someone is interested: OR rst manual

The manual source files are simple text files, can be edited with any text editor, e.g. notepad++. There was a make.bat created by Sphinx/Python, which I used to build the html result. The downloadable zip contains the built html as well, can be checked by opening the _build/html/index.html file with any web browser.

[James Ross]

gpz, on 23 December 2015 - 01:33 AM, said:

Just for fun, I converted the first 6 sections of the manual to reStructuredText. It was fast, since these sections are short ones, so they were good for experimenting. The result is quite pretty, and for me it is much more less disgusting to work with a manual in such a format than with Word.

I uploaded the result here, if someone is interested: OR rst manual

The manual source files are simple text files, can be edited with any text editor, e.g. notepad++. There was a make.bat created by Sphinx/Python, which I used to build the html result. The downloadable zip contains the built html as well, can be checked by opening the _build/html/index.html file with any web browser.

Looks good to me, and being able to perform normal text diffs is a plus too. We should be able to generate a PDF from it as well, although the tooling seems to completely broken right now.

What do other people think about using reStructuredText for documentation?

[Sid P.]

It is not clear to me what tool gpz used to convert his sample from the OR Manual to plain text to build his html text. Word will save the manual in html text, but writes all of the images in a separate folder (does not use the author's identifying alternate-text to name them, but creates arbitrary names), and does not automatically build the links to them in the text. Unless I missed something.. Otherwise it looks very interesting.


Cheers,

[gpz]

James Ross, on 01 January 2016 - 09:48 AM, said:

We should be able to generate a PDF from it as well, although the tooling seems to completely broken right now.

By installing "MikTex" it was easy to generate a pdf as well, with just simply running `make.bat latexpdf`. MikTex downloads and installs additional modules needed for it at runtime, when some new function is first used in docs, and of course at first running time.

[gpz]

Sid P., on 01 January 2016 - 10:39 AM, said:

It is not clear to me what tool gpz used to convert his sample from the OR Manual to plain text to build his html text. Word will save the manual in html text, but writes all of the images in a separate folder (does not use the author's identifying alternate-text to name them, but creates arbitrary names), and does not automatically build the links to them in the text. Unless I missed something.. Otherwise it looks very interesting.

Plain text files is easiest to produce with plain text editors. :) I used Notepad++ for creating it. For writing such a document, one has to learn the syntaxes, how to mark a heading, a bulleted list, how to reference an image, how to make emphasis, code snippet, etc... Look at e.g. this quick reference guide, but there are tons of such tools on the net. I just copied-pasted the text from Word to Notepad++, and fixed the resulted formatting. Open my .rst files to see how it's done. Index.rst is the master document, listing the sub-files (without the ".rst" extension).

[gpz]

I have uploaded the git branch of this to my github fork, so that it may be git-cloned easily, if someone wants to get itto work on it, if agreed to go this way.

[James Ross]

gpz, on 04 January 2016 - 09:26 PM, said:

By installing "MikTex" it was easy to generate a pdf as well, with just simply running `make.bat latexpdf`. MikTex downloads and installs additional modules needed for it at runtime, when some new function is first used in docs, and of course at first running time.

I tried to use the direct-to-PDF option of "rst2pdf" and it was just broken. "make.bat latexpdf" doesn't work for me as I don't have any build tools ("make") in my path, but calling MikTex directly with "pdflatex OpenRails.tex" works, so I should be able to automate the building of the documentation if we switch to reStructuredText.