You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "David Roussel (JIRA)" <ji...@codehaus.org> on 2007/10/04 13:15:09 UTC
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_108998 ]
David Roussel commented on DOXIA-138:
-------------------------------------
In Trac (the python based wiki http://trac.edgewall.org/) section heading produce 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 disabiguated
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.
> Review and clarify the APT guide
> --------------------------------
>
> Key: DOXIA-138
> URL: http://jira.codehaus.org/browse/DOXIA-138
> Project: Maven Doxia
> Issue Type: Task
> Components: Documentation, Module - Apt
> Affects Versions: 1.0-alpha-8
> Reporter: Lukas Theussl
> Fix For: 1.0
>
>
> Our current apt guide is a copy of http://www.xmlmind.com/_aptconvert/docs/userguide2.html, but there are several issues that need clarification, eg
> * case sensitivity and white space handling in anchors
> * anchors for section titles
> * figure handling, esp extensions
> * tables: is the first line always a header row?
> Some of these depend on how things are going to be implemented.
> We also decided to remove the apt guide at http://maven.apache.org/guides/mini/guide-apt-format.html and only keep the one on the doxia site.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira