You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Lukas Theussl (JIRA)" <ji...@codehaus.org> on 2007/07/18 08:58:13 UTC
[jira] Created: (DOXIA-138) Review and clarify the APT guide
Review and clarify the APT guide
--------------------------------
Key: DOXIA-138
URL: http://jira.codehaus.org/browse/DOXIA-138
Project: 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "David Roussel (JIRA)" <ji...@codehaus.org>.
[ 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Lukas Theussl (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_104917 ]
Lukas Theussl commented on DOXIA-138:
-------------------------------------
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
> 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Denis Cabasson (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_102818 ]
Denis Cabasson commented on DOXIA-138:
--------------------------------------
Tables' first row is not a header row.
Header cell are defined by a aditionnal pipe char '|' beginning the cell.
For example :
{quote}
*------+-----------------+
|| title || subject |
*------+-----------------+
| My | Oh my |
*------+-----------------+
{quote}
And that should definitly be somewhere in the documentation.
> 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Lukas Theussl (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_102857 ]
Lukas Theussl commented on DOXIA-138:
-------------------------------------
Interesting. I didn't know that! :) However, aptconvert doesn't support this, does it? I wonder what other undocumented features our AptParser is hiding...
> 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
[jira] Issue Comment Edited: (DOXIA-138) Review and clarify the APT
guide
Posted by "David Roussel (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_108998 ]
David Roussel edited comment on DOXIA-138 at 10/4/07 6:14 AM:
--------------------------------------------------------------
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 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.
was:
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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Denis Cabasson (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_103924 ]
Denis Cabasson commented on DOXIA-138:
--------------------------------------
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....
> 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
[jira] Issue Comment Edited: (DOXIA-138) Review and clarify the APT
guide
Posted by "Denis Cabasson (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_102818 ]
Denis Cabasson edited comment on DOXIA-138 at 7/20/07 3:14 PM:
---------------------------------------------------------------
Tables' first row is not a header row.
Header cell are defined by a aditionnal pipe char '|' beginning the cell.
For example :
{noformat}
*--------+------------------+
|| title || subject |
*--------+------------------+
| My | Oh my |
*--------+------------------+
{noformat}
And that should definitly be somewhere in the documentation.
was:
Tables' first row is not a header row.
Header cell are defined by a aditionnal pipe char '|' beginning the cell.
For example :
{quote}
*------+-----------------+
|| title || subject |
*------+-----------------+
| My | Oh my |
*------+-----------------+
{quote}
And that should definitly be somewhere in the documentation.
> 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
[jira] Closed: (DOXIA-138) Review and clarify the APT guide
Posted by "Lukas Theussl (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Lukas Theussl closed DOXIA-138.
-------------------------------
Assignee: Lukas Theussl
Resolution: Fixed
Fix Version/s: (was: 1.0)
1.0-beta-1
Documented the points above on the doxia site.
> 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
> Assignee: Lukas Theussl
> Fix For: 1.0-beta-1
>
>
> 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Denis Cabasson (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_102914 ]
Denis Cabasson commented on DOXIA-138:
--------------------------------------
I don't know about aptconvert (I don't know this guy anyway).
The header cells fix was provided by brett :
[brett|http://mail-archives.apache.org/mod_mbox/maven-doxia-commits/200512.mbox/%3C20051230005736.29217.qmail@minotaur.apache.org%3E]
Revision in SVN is [359951|http://svn.apache.org/viewcvs?rev=359951&view=rev] (quite some time ago)
It is still in place in AptParser and it's working.
> 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Lukas Theussl (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_109016 ]
Lukas Theussl commented on DOXIA-138:
-------------------------------------
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.
> 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "David Roussel (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_109021 ]
David Roussel commented on DOXIA-138:
-------------------------------------
Lukas,
I agree it's an output level concern.
David
> 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
[jira] Commented: (DOXIA-138) Review and clarify the APT guide
Posted by "Denis Cabasson (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_107071 ]
Denis Cabasson commented on DOXIA-138:
--------------------------------------
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.
> 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
[jira] Issue Comment Edited: (DOXIA-138) Review and clarify the APT
guide
Posted by "David Roussel (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/DOXIA-138?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_108998 ]
David Roussel edited comment on DOXIA-138 at 10/4/07 6:14 AM:
--------------------------------------------------------------
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.
was:
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 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.
> 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