Documentation Style for printed documentation

[ct]

As well as we working on stylesheets for HTML generation, someone needs to care for stylesheets and formatting of generated PDF's.

This job involves a bit asciidoc/docbook/dblatex RTFM'ing and improving existing stylesheets or creating new ones.

The default a2x pdf output looks like it enables all bells and whistles but it does not look nice. A non complete lists of what has to be investigated:

• Use Vector formats for graphics (thats already explained in ticket #171)
• Improve table rendering on pages so that they fit nice (big tables on their own pages in landscape?)
• Support different paper formats (Letter, A4, A5)
• duplex (book) printing, needs odd/even page numbering/styles
• proper generation of toc/index/glossary/titlepage and so on
• General style eye-candy, for example currently paragraphs get a "Example #." text which is improper, i have not found out how to disable that. Also the document revision table at the first page isn't used by us. Prettier recognizable fonts and general typeset/artwork.

I put this little higher on the priority because it would be nice to get this done before FrOSCon so we can hand out some printed documentation to interested users ("Lumiera from Outer Space", and the NoBug manual)

[ct]

As example to show what I am speaking about, I uploaded the nobug manual generated with:

a2x -v -a toc -d book -f pdf nobug_manual.txt

to

http://lumiera.org/nobug_manual.pdf

Basically it's already ok but there are a lot details which should be improved.

[pseudoruprecht]

My findings so far:

• the DocBook LaTeX styles do indeed enable all bells and whistles
• worse: they override almost everything of the LaTeX layout defaults there are to override
• even worse: they do it low-level, so that many user oriented means of taking influence (e.g. setting page size, twoside printing for books) no longer work and now have to be reset low-level as well
• including/excluding content (e.g. the revision history) can be influenced at the XSLT stage; by cmdline parameters to a2x like --dblatex-opts="-Platex.output.revhistory=0" or in xsl files (I hope they don't abuse XSL the way the .sty do with LaTeX)

From my first expedition into dblatex/DocBook-land I'd say it's easier to start from scratch than to wade through all styles (yes, they just love to branch) and then override the settings there.

A first step will be to find out what subset of DocBook AsciiDoc uses after the conversion to XML, especially in the realm of tables and listings.

[pseudoruprecht]

Another option might be to use the Asciidoc LaTeX backend (marked as experimental). The complexity of DocBook is one of the reasons why Asciidoc even exists. Why bother with it unless absolutely neccessary?

asciidoc --unsafe --backend=latex nobug_manual.txt

fails, though, with:

asciidoc: WARNING: missing template section: [abstractblock]
asciidoc: FAILED: [tabledef-default] missing section: [tabletags-header]

I will investigate this before returning to the DocBook pond.

[ct]

Replying to pseudoruprecht:

Another option might be to use the Asciidoc LaTeX backend (marked as experimental). The complexity of DocBook is one of the reasons why Asciidoc even exists. Why bother with it unless absolutely neccessary?

asciidoc --unsafe --backend=latex nobug_manual.txt

fails, though, with:

asciidoc: WARNING: missing template section: [abstractblock]

this are asciidoc.conf deficiencies (or maybe missing in my documentation) should be trivial to fix

asciidoc: FAILED: [tabledef-default] missing section: [tabletags-header]

I will investigate this before returning to the DocBook pond.

I like the idea, generally i think before reinventing the wheel one should be sure that it makes sense and the new thing is sustainable and maintainable for the future. But with latex I don't see problems in this area, what works now will certainly work in 50 years still :). Note about you got different rendering than me: my asciidoc is fairly old, I know there are improvements and its ok to require newer asciidoc versions for the printed documentation looking nicer. While the default targets (html and manpage soon) should stay useable on older versions. Also i am little reluctant about using an experimental feature, please investigate how complete and future proof that is before we depend on it (if there is a chance that it might be dropped, then not)

[pseudoruprecht]

Replying to ct:

Replying to pseudoruprecht:

asciidoc --unsafe --backend=latex nobug_manual.txt

fails, though, with:

asciidoc: WARNING: missing template section: [abstractblock]

this are asciidoc.conf deficiencies (or maybe missing in my documentation) should be trivial to fix

These are actually deficiencies in the latex.conf, as I found out here:

 http://www.mail-archive.com/asciidoc@googlegroups.com/msg00163.html

I like the idea, generally i think before reinventing the wheel one should be sure that it makes sense and the new thing is sustainable and maintainable for the future. But with latex I don't see problems in this area, what works now will certainly work in 50 years still :).

Which can't be said about dblatex or db2latex or PassiveTeX (did I forget one? Jade?). What I don't like about them - I can't state this too often - is that they override most of the defaults typographers laboriously worked into LaTeX (or use TeX directly, as in the case of PassiveTeX); as to why - I don't know. Perhaps they try to mimic some obscure reference layout, e.g. the HTML output from DocBook rendered with Firefox 2.0.15 on Mac OS X 10.5 and then printed to a file. Something like that.

Right now I don't feel like implementing the next failed DocBook -> LaTeX solution.

Note about you got different rendering than me: my asciidoc is fairly old, I know there are improvements and its ok to require newer asciidoc versions for the printed documentation looking nicer. While the default targets (html and manpage soon) should stay useable on older versions. Also i am little reluctant about using an experimental feature, please investigate how complete and future proof that is before we depend on it (if there is a chance that it might be dropped, then not)

It's not complete, e.g. from what I see tables are only partially implemented. And cross references don't work if the target tag contains anything but [A-Za-z:]. This is a limitation of LaTeX. We could cirumvent it by restricting crosslink target names to these characters in our Asciidoc, but it would be nicer to fix the latex.conf once and for all. Which would solve the question of completeness, (though not that of future proofness :) ) Augmenting the Asciidoc LaTeX backend with the features we need is something I feel more up to than understanding DocBook and the various tools to get so-called "LaTeX" out of it, let alone tweak them to sanity.

I for one think upstream AsciiDoc wouldn't mind a more complete LaTeX backend. Perhaps more than they care about a professional NLE with a viewer that follows a pull model instead of a push model. (see? I've been to outer space ;) )

[pseudoruprecht]

Resume of day 1 here at Asciidoc:

• I need newlines in the backend output, but I don't know how (I can't believe that one has to write a filter just to add a \n at the start/end of the input from | ???)
• Tables require a filter to work. We need to actually let LaTeX typeset the tables beforehand, adding row by row; the first time LaTeX complains about Overfull \vbox, we know where to split. This is necessary to avoid longtable, which is not so good at setting table width according to cell content (tabulary seems best suited to me). Things like colspan will still be a challenge (but if your tables are real tables and not some Excel-inspired crap you don't need those, anyways ;) )
  • a hackish fix for the colspan problem would be to repeat the content of the cell that spans in all cells that would be spanned. Colspans are there to avoid this duplication, but since we're generating the typeset document automatically and not by pushing movable type around over some badly lit workbench, it could be a preliminary solution that is "good enough"
    • this will look really ugly when the cell that spans is part of the table header

I now understand why tables were implemented so late in the game in KOffice :)

[ct]

Replying to pseudoruprecht:

Resume of day 1 here at Asciidoc:

• I need newlines in the backend output, but I don't know how (I can't believe that one has to write a filter just to add a \n at the start/end of the input from | ???)

You write newlines literally into the output:
[foo-macro]
\foo{}
|

[bar-macro]
\begin{bar}
|
\end{bar}

Possibly some string escaping would work to, I never tried

• Tables require a filter to work. We need to actually let LaTeX typeset the tables beforehand, adding row by row; the first time LaTeX complains about Overfull \vbox, we know where to split. This is necessary to avoid longtable, which is not so good at setting table width according to cell content (tabulary seems best suited to me). Things like colspan will still be a challenge (but if your tables are real tables and not some Excel-inspired crap you don't need those, anyways ;) )

I don't exactly understand your problem here, do you try to automatize tables based overfull? Typesetting tables is always a bit challenging. I'd suggest to make is simple and not so much automated maybe the user has to define what kind of table to use for each one. The catch is that different paperformats will have some problems (for example, tabular on A5 won't fit you need table). I don't think you need to put much automatism there, just having some simple switch either global or possibly per table (if paperwidth<200mm then use table, else use tabular) should be enough. We get used to the table rendering and can do test renders and fix the tables. (table/tabular was just and example you can use whatever table-rendering package you think will do the job best). Anyway simpler is better. Its not the case that we need to generate output for different paper-formats and give it to print without reviewing it. Small A5 is only a wish, not a requirement. Having only A4 and Letter rendering reliable (even with some human intervention) is OK.

• a hackish fix for the colspan problem would be to repeat the content of the cell that spans in all cells that would be spanned. Colspans are there to avoid this duplication, but since we're generating the typeset document automatically and not by pushing movable type around over some badly lit workbench, it could be a preliminary solution that is "good enough"
  • this will look really ugly when the cell that spans is part of the table header

[pseudoruprecht]

I forwarded my problem to the AsciiDoc support group at  http://groups.google.com/group/asciidoc/
(Since I'm a new member there, my message must go though moderation; dunno how long this will take. I'll post the link to the thread as refernce then.)

In the future, I will post to this ticket only as I tackle the issues from the wishlist one by one.

[ct]

Replying to pseudoruprecht:

I forwarded my problem to the AsciiDoc support group at  http://groups.google.com/group/asciidoc/
(Since I'm a new member there, my message must go though moderation; dunno how long this will take. I'll post the link to the thread as refernce then.)

In the future, I will post to this ticket only as I tackle the issues from the wishlist one by one.

lorem ipsum, trac/mailinglist test blah blah

[ct]

Replying to ct:

Replying to pseudoruprecht:

I forwarded my problem to the AsciiDoc support group at  http://groups.google.com/group/asciidoc/
(Since I'm a new member there, my message must go though moderation; dunno how long this will take. I'll post the link to the thread as refernce then.)

In the future, I will post to this ticket only as I tackle the issues from the wishlist one by one.

lorem ipsum, trac/mailinglist test blah blah

again, turned the recipient filter off now ...

[pseudoruprecht]

Verbatim works now, although not as pretty as it could be (e.g. no frames around code blocks). I move on for now and fix it later ;)

The following from the wishlist already works (LaTeX built-in, unless you break it by insane overrides):

• Support different paper formats (Letter, A4, A5)
• duplex (book) printing, needs odd/even page numbering/styles

Next on my agenda is table support. This will be tricky.

[pseudoruprecht]

verbatim, reloaded:

The problem is how verbatim environments are implemented in LaTeX. But why use them, anyways? The reason for their existence is mainly to keep the LaTeX source files understandable to the author, without those funny escape commands in verbatim source code. But the way they are used here, they are just an interim stage to the final PDF, no one is expected to ever tinker with those .tex files generated from AsciiDoc. So it would be straightforward to use the usual substitution patterns and not verbatim, thus not entering LaTeX verbatim hell, which is not the place where one wants to be.

Problem I see coming is how AsciiDoc handles \n in the conversion: How _not_ to have them whitespace-ized altough we're not using the verbatim substitution patterns?

[pseudoruprecht]

OK, one small note re tables:

Replying to pseudoruprecht:

• Tables require a filter to work. We need to actually let LaTeX typeset the tables beforehand, adding row by row; the first time LaTeX complains about Overfull \vbox, we know where to split.

Of course, this loop is only started if the table *doesn't* fit on one page. Preferably, the package used (tabulary?) has to support placement in a float environment.