You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Benjamin Bentmann (JIRA)" <ji...@codehaus.org> on 2007/12/18 01:10:57 UTC
[jira] Created: (MSITE-281) Employ consistent
typesetting/formatting
Employ consistent typesetting/formatting
----------------------------------------
Key: MSITE-281
URL: http://jira.codehaus.org/browse/MSITE-281
Project: Maven 2.x Site Plugin
Issue Type: Improvement
Affects Versions: 2.0-beta-6
Reporter: Benjamin Bentmann
Priority: Minor
Attachments: site.patch
Well, typesetting/formatting surely belongs to the "peanuts" of life. This issue is a small attempt to raise sensibility for this topic.
The attached patch contains various minor (mostly typographic) changes intended to improve readability/consistency of the documentation. Some of the rules I chose to follow are surely controversial and a matter of taste:
- Hyperlinks should be readable/understandable without their surrounding context (a best practice for web design, e.g. see [Stanford Online Accessibility Program|http://soap.stanford.edu/show.php?contentid=46])
- Headline style capitalization for page/section titles (see also [Capitalization of Headings and Titles|http://www.tc-forum.org/topicmai/ml03capi.htm])
- Double quotation marks instead of single quots for quoted text ([Quotation Marks and Direct Quotations|http://www.informatics.sussex.ac.uk/department/docs/punctuation/node30.html])
- Proper casing for acronyms (e.g. POM instead of pom, but {{scp}} if one wants to refer to the protocol part of a URL literally)
- Monospaced font for file/path names, URLs, plugin goals, command prompts
- Uppercase first letter for plugin names (it might just be my German habit, but I consider "the Clean Plugin" more understandable than "the clean plugin" since I can realize the reference to a name more quickly)
Indepedently from the patch getting rejected or not, it might by worth to create some guidelines (house-style) that Maven developers can follow for their documentation, similar to the [Maven Plugin Documentation Standard|http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation] and the code formatter style.
@Dennis: I did not re-order the plugin goals in {{index.apt}} this time, although I would recommend so. To me, the current order seems quite random, e.g. why is site:site listed after site:deploy when one usually would invoke site:site first? I consider the following order (not optimal but just) more intuitiv as it groups related goals:
- site:site
- site:site-deploy
- site:run
- site:stage
- site:stage-deploy
- site:attach-descriptor
--
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: (MSITE-281) Employ consistent typesetting/formatting
Posted by "Dennis Lundberg (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/MSITE-281?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Dennis Lundberg closed MSITE-281.
---------------------------------
Assignee: Dennis Lundberg
Resolution: Fixed
Fix Version/s: 2.0-beta-7
Patch applied Thanks!
There were a couple of hunks that failed when I applied the patch, in index.apt and faq.fml, but I think I managed to get them in manually.
I also reordered the plugin goals according to your suggestion.
As for the guidelines I opened another issue for that: MNGSITE-43.
> Employ consistent typesetting/formatting
> ----------------------------------------
>
> Key: MSITE-281
> URL: http://jira.codehaus.org/browse/MSITE-281
> Project: Maven 2.x Site Plugin
> Issue Type: Improvement
> Affects Versions: 2.0-beta-6
> Reporter: Benjamin Bentmann
> Assignee: Dennis Lundberg
> Priority: Minor
> Fix For: 2.0-beta-7
>
> Attachments: site.patch
>
>
> Well, typesetting/formatting surely belongs to the "peanuts" of life. This issue is a small attempt to raise sensibility for this topic.
> The attached patch contains various minor (mostly typographic) changes intended to improve readability/consistency of the documentation. Some of the rules I chose to follow are surely controversial and a matter of taste:
> - Hyperlinks should be readable/understandable without their surrounding context (a best practice for web design, e.g. see [Stanford Online Accessibility Program|http://soap.stanford.edu/show.php?contentid=46])
> - Headline style capitalization for page/section titles (see also [Capitalization of Headings and Titles|http://www.tc-forum.org/topicmai/ml03capi.htm])
> - Double quotation marks instead of single quots for quoted text ([Quotation Marks and Direct Quotations|http://www.informatics.sussex.ac.uk/department/docs/punctuation/node30.html])
> - Proper casing for acronyms (e.g. POM instead of pom, but {{scp}} if one wants to refer to the protocol part of a URL literally)
> - Monospaced font for file/path names, URLs, plugin goals, command prompts
> - Uppercase first letter for plugin names (it might just be my German habit, but I consider "the Clean Plugin" more understandable than "the clean plugin" since I can realize the reference to a name more quickly)
> Indepedently from the patch getting rejected or not, it might by worth to create some guidelines (house-style) that Maven developers can follow for their documentation, similar to the [Maven Plugin Documentation Standard|http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation] and the code formatter style.
> @Dennis: I did not re-order the plugin goals in {{index.apt}} this time, although I would recommend so. To me, the current order seems quite random, e.g. why is site:site listed after site:deploy when one usually would invoke site:site first? I consider the following order (not optimal but just) more intuitiv as it groups related goals:
> - site:site
> - site:site-deploy
> - site:run
> - site:stage
> - site:stage-deploy
> - site:attach-descriptor
--
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