Uploaded image for project: 'Maven Site Plugin'
  1. Maven Site Plugin
  2. MSITE-281

Employ consistent typesetting/formatting

    XMLWordPrintableJSON

Details

    • Improvement
    • Status: Closed
    • Minor
    • Resolution: Fixed
    • 2.0-beta-6
    • 2.0-beta-7
    • None
    • None
    • Patch

    Description

      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)
      • Headline style capitalization for page/section titles (see also Capitalization of Headings and Titles)
      • Double quotation marks instead of single quots for quoted text (Quotation Marks and Direct Quotations)
      • 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 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

      Attachments

        1. site.patch
          21 kB
          Benjamin Bentmann

        Activity

          People

            dennisl@apache.org Dennis Lundberg
            bentmann Benjamin Bentmann
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: