User guide complete overhaul (with fruits of labour!)

[Fifis]

Dear friends,

I sent this as an e-mail message to the address root@... but got no reply. However, I think that this issue might deserve broader coverage.

One thing troubles me: many Linux users are fond of having “everything up-to-the-date from the latest repositories”, but... the documentation does not keep pace at all. Just look at the histogram of the state of affairs (as of 25 January 2015).



Please bear in mind that I do not want to offend anyone or criticise the Linux Mint translation maintainers: they are doing everything right! My point is: it could have been done more efficiently, so we can follow the example of other software developers. Let’s just have a few examples: gretl, R, Stata, MATLAB and Octave (their latest versions) have their “basic manuals” written in LaTeX. Coincidence? Conspiration? I don’t think so. Convenience? Versatility? Yay!

Problem is: so far, the documentation had been supplied in ODT format only. It is great, but... if changes are introduced in one section of the document, how can one make sure that they are accounted for in all multilingual versions? How do other people know what has been added? On the other hand, should we have used LaTeX, we could track all commits and changes with zero effort. Besides that, it could facilitate screenshot management (with explicit image files that are not embedded in the bloated XML document in some obscure way).

Let’s jump ahead a bit: I already did the conversion. What are the benefits? Let us compare the old and the new version in terms of editing and management.

Old version (LibreOffice)

1. In order to merge changes to the document made by two people, you need to open the two documents and invoke comparison procedure (Edit — ...). No command-line tool does that. If changes are made by two or more people, this is cumbersome and requires manual (let’s be honest, menial) labour.
2. Images are incorporated in one large file together with the text. In order to replace them, you have to be careful, and if you accidentally drag the rescaling slider—may God have mercy on your output.
3. Want a shared fragment of text (e.g. “LM history”, “Conclusion”) across several documents? Forget that, and copy-paste, copy-paste. Do not forget to redo the whole procedure for all files if you want to change one word in that fragment. Or you can have a separate file with the master text, but then copy-paste, copy-paste...
4. The look of the document depends on the person who edited it. In order to obtain high-quality layout, we need someone to typeset them properly.
5. Imagine someone pasted a heavy image into the document. What can I do in order to re-compress it using the most preferrable algorithm? (Lifting hands in dismay.)

New version (LaTeX)

1. If several people edit the files, you can use a wide range of tools (diff, Meld, vimdiff, tkdiff, or any high-level VCS). Easy to commit changes, easy to incorporate them in the master version even if the branching is wild.
2. Images are distinct files. If you need to replace one image, you need not open the whole document—just do whatever you want to the image of your interest. Image size can be set in terms of either explicit dimensions or page percentage.
3. You can split the document into sections and subsections that are included from other files. You need to make only one change to only one file, and run the “compile all” script.
4. After we declare the general desired parameters, the system unleashes the might of its typographic optimisation algorithms onto the poor document, thus making in look none other than perfect.
5. We immediately see which screenshots weigh way too much. We deal with them straight away.

See the faux small caps on the left and lines underlining the header dots... ugh. On the right: clear leaders, nested structure, and these names ones are obviously clickable. Oh, and did I say that the new file size halved because of the optimisation of PNG screenshots?

I did all the hard work: converted the document, compared the Cinnamon and MATE .odt files, incorporated all changes and made it ready for future changes (e.g. addition of XFCE, KDE and whatever versions of the manual) using conditional expressions that depend on the name of the manual being compiled.

First, it was converted using Writer2LaTeX, and then, I just thoroughly cleaned and formatted it “comme il faut”. The editable text is plain, everything is visible, all the shorthands are defined in the preamble... you know... almost all cool GNU software, especially science-y, use it... just look at it.

What else do our manuals need? Correct, guidelines! All future translators are invited to use the existing style file and ready macros in order to facilitate their work. They need not do anything except the translation! All the typesetting has already been done by the almighty pdfLaTeX.

There will be no need to keep four huge source files and painstakingly replace the contents depending on the desktop environment. Never ever! The TeX macros allow us to write things like

Code: Select all

You are reading the \CMKX{ground-breaking Cinnamon}{awesome MATE}{jaw-dropping KDE}{dazzling XFCE} manual. \ifDE{cinnamon}{Only Cinnamon users deserve this magnificent announcement!}

The last thing remaining is to incorporate these changes. Who is in charge of the User Manual translations? If you like this idea (I hope!), will it be github’bed in a “doc-tex” branch or whatever you like?

I wanted to attach the two PDF’s (750 kB each) and the source code (compressed XZ, 1 MB), but this forum does not allow more than 100 kB. Here are the remastered manuals:
http://kostyrka.ru/donate/cinnamon.pdf
http://kostyrka.ru/donate/mate.pdf
http://kostyrka.ru/donate/Mint-manual.tar.xz

[xenopeek]

Sounds like you already did a lot of work! One misunderstanding on your part I think; Linux Mint 17.1 documentation is created with Publican software (the documentation is installed on your system and uses your system's help interface to access it). You can find the mintdoc repository here: https://github.com/linuxmint/mintdoc. For next version I think it's still planned to take the next step with this and make it easy for users to add their translations to it.

The user guides of Linux Mint 17.x in PDF/ODF format on the main website are all created by users of Linux Mint. The Linux Mint developers only wrote the Linux Mint 16 and earlier English user guides; other user guides have always been created by users of Linux Mint. The developers are focusing on Publican as the way forward.

In short, the developers had already come to the conclusion PDF/ODF format was less that ideal for keeping the document up to date and especially a lot of redundant effort in translation. Have a look at mintdoc; perhaps this also addresses the core of the problem you saw? I don't know how your format compares to Publican, but IIRC Publican would allow individual strings to be translated--meaning with a new version of the user guide, translators would only need to change the added/changed strings--massive reduction of effort and simplifying of the work.

In any case, there is just too much email sent these days--not an excuse but just a fact of life that it can take a while before you get a reply. And yes, sometimes something will get missed and not get a reply For ideas like these it's usually best to talk to the developers directly, specifically try and catch Clem on #linuxmint-dev on irc.spotchat.org (or open HexChat / Konversation from your menu and type /join #linuxmint-dev to go to this channel). Come say hi anyway Drop your idea there, or if has been more than a week or two since your email ask if Clem has looked at it yet.

[Fifis]

Thank you very much for your reply!

Well, the current help system should remain “as is” if it is convenient to translate. There is no problem with it.

Much as I respect the DocBook XML format, the way the User Guide source files are made for some languages (e.g. Russian) seems... somewhat counterintuitive (especially line-breaking). The English version seems to be nicely split in paragraphs and so on, but what seemed strange to me is the presence of such artifacts as double spaces after not-end-of-sentence (common in WYSIWYG editors) and screenshots with seemingly broken proportions (i.e. non-square pixels, squeezed) in the ODT and the official PDF version (e.g. MATE “Keyboard Layout” screenshot, although the PNG’s are perfectly normal and the XML code is fine, too!). Usually automated build tools account for such things, but here the reason must be researched more thoroughly, and it is not necessary to do this for the User Guide PDF at all.

Just in order not to seem a fanatical LaTeX addict who wished to convert the whole Earth into this system, I should mention that maybe it would be nice if only the User Guide were converted that way, because it is common practice for other software to have quick and detailed explanations invoked through something like Publican or other XML stuff, and the “theoretical course” to be written “like a book” separately.

Sorry for thinking that the ODT files were the original source. I was completely mistaken, and after seeing all that, I realised that the whole manual had existed in a plain text format in github (coundn’t find it initially). Seems it was kind of forcing an open door, because those LibreOffice drawbacks I had castigated are virtually non-existent. In this case, let other users determine which version they prefer æsthetically: the LaTeX one or the one that is constructed from the mintdoc/books/User_Guide branch.

Compared to the mintdoc/books/User_Guide/en-US/, as you can see in the previously attached XZ archive, the format I suggest is very similar to what exists in that branch: separate chapters in separate files, common text for common parts, plus context-dependent macros expanding with respect to the DE name... almost the same, except that DocBook would be better for digital HTML-like books for e-book readers, and LaTeX is better for professional technical books requiring commands of arbitrary complexity and is optimized for print on paper or display on computer screen with all possible microtypographic enhancements.

Ah, after looking at all those XML sources, I understood that many identifiers, such as “guilabel” or similar were omitted just because they did not make it to the ODT format, but it is pretty quick to transmute them into TeX macros. Even pandoc is not needed; since we already have the TeX file, we can search for non-standard tags (they can’t be numerous) and add them to the TeX version (again, if enough users, including administrators, vote for it).

I shall try HexChat as you recommended.

[xenopeek]

Sorry for thinking that the ODT files were the original source. I was completely mistaken, and after seeing all that, I realised that the whole manual had existed in a plain text format in github (coundn’t find it initially).

No, you were correct:

• The PDF format User Guides that you can download from the main website have the ODF files are their sources.
• From Linux Mint 17.1, there is a replacement for the User Guide--created with Publican and included on the Linux Mint ISO. Source is the mintdoc repository on GitHub. You'll find "Help" in your menu, and opening that opens the new User Guide using the help system.