Review and clarify the APT guide

Tables' first row is not a header row.

Header cell are defined by a aditionnal pipe char '|' beginning the cell.

For example :

 
*--------+------------------+
|| title || subject         |
*--------+------------------+
| My     | Oh my            |
*--------+------------------+

And that should definitly be somewhere in the documentation.

Interesting. I didn't know that! However, aptconvert doesn't support this, does it? I wonder what other undocumented features our AptParser is hiding...

I don't know about aptconvert (I don't know this guy anyway).

The header cells fix was provided by brett :
brett

Revision in SVN is 359951 (quite some time ago)

It is still in place in AptParser and it's working.

the guide states :
"Section titles are implicitly defined anchors." however, it doesn't seem to be the case.

Still for anchors, they are rewritten in minuscule, with spaces distilled to '_'. That should be somewhere in the documentation....

I really don't like section titles as anchors. IMO, if you want to reference a section, you should explicitly provide an anchor.

The use of automatically constructed anchors from section titles was discouraged in one of the last versions of the m1 xdoc plugin [1] as it only led to trouble (see MPXDOC-158 and MPPDF-40 for related discussions). We will have the same sort of problems in doxia if we implement that, so my preference would be to remove this statement from the user guide.

[1] http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html#Referencing_sections_and_subsections

Section titles as anchors are definitely not a good idea.

My point was only to review the documentation and see where the documentation and DOXIA weren't consistants.

The way it is done in xdoc is quite good actually. Currently my problem with anchors is that you can't create an anchor without any text, which would be handy to refer to a section. There are times when I don't want the anchor id (which can be kind of unreadable) to be displayed to the end user.

In Trac (the python based wiki http://trac.edgewall.org/) section headings are automatically anchors. This works well because:

• the CSS shows an link to the anchor when a reader hovers of the heading, this makes it easy to discover an anchor, and copy the link to email to someone
• duplicate headings are disambiguated

The first time I was this in Trac I was really impressed. I'd never really seen anchors as a useful feature before in HTML. They had always been used inconsistently by document authors. And they were only for use by document authors, since it was easy for a user to discover them.

The Trac model of anchors means the author doesn't need to think about anchors (and most authors don't anyway) but the user is able use them easily. Plus if you are writing a new page and want to refer to the section in another page, you don't have to go to the other page and add the anchor first, it's just there to be used.

Try using the anchors in Trac and see what I mean. It just works.

I don't deny that it's a useful feature, I used it a lot myself during my m1 days. The problem is that Doxia is a multi-format document processing engine, and while section anchors are usually fine for xhtml output, it simply won't work with other formats. Eg the example given at MPPDF-40 will make the fop pdf renderer bomb. My point of view is that such sink-dependent features should be implemented by a specialised, low-level sink, (ie the part of doxia that produces the end-user output), eg the SiteRendererSink in the site plugin, where you know that the output will always go to html. No parser should emit any event that was not there in the original document. This issue is about the apt format, if the apt parser emits anchors for section titles (before you know which kind of sink is going to consume the event), then there's going to be trouble.

Lukas,

I agree it's an output level concern.

David

Documented the points above on the doxia site.