Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-5068830

Fix errors in J2SE man pages due to conversion from HTML

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P4
    • Resolution: Fixed
    • Affects Version/s: 5.0, 6
    • Fix Version/s: 6u10
    • Component/s: docs
    • Subcomponent:
    • Resolved In Build:
      b01
    • CPU:
      generic, x86
    • OS:
      generic, linux

      Backports

        Description

        Fix the errors in the man pages that occurred in the conversion from HTML
        tool docs. A few examples of errors follow. This is just a brief list.
        There are numerous other bugs in these and other tool pages.

        Solaris Javadoc man page:

            PROBLEM:
              javadoc [options] [packagenames] [sourcefilenames] [subpack-
              ages [pkg1:pkg2:...]] [@argfiles]

            CORRECTION:
            The "subpackages" term should be "-subpackages" and not be underlined,
            because it is a literal.

            PROBLEM:
            {@link package.class#member
                   label}" 6 Inserts an in-line link with visible text

            CORRECTION:
            {@link package.class#member label}
                   Inserts an in-line link with visible text
            Same problem with {@linkplain}

            PROBLEMS:
            These first two options are missing the leading dash,
            the third is missing the space after "-tag":
           
            quiet Shuts off non-error and non-warning messages, leaving
            stylesheetfile path/filename
            -tagtagname:Xaoptcmf:"taghead"

            PROBLEM:
            These two paragraphs start with corruptions:
            ",nf" and ".ds ]F"

               ,nf /** * @param <E> Type of element stored in a list
               */ public interface List<E> extends Collection<E> { }

               " .ds ]F
                  @see<ahref=URL#value>label</a> Adds a link as defined
                  by URL#value. The URL#value is a relative or absolute

        Linux Javadoc man page:

            PROBLEM:
            None of the 1.5.0 changes were incorporated -- two new tags
            (@code, @literal) and two new options (-notimestamp and
            -keywords).

        Solaris Jar man page -- all of thes synopses are incorrect -- here is just one:

            PROBLEM:
              jar [-c[v0M] f] [jarfile] [ -C dir ] inputfiles [[ -Joption
              ]]

            CORRECTION:
              Create jar file
                jar c[v0M]f jarfile [-C dir] inputfiles [-Joption]


        Appletviewer man page:
            PROBLEM:
            -J javaoption

            CORRECTION:
            -Jjavaoption
            There must be no space after the "J"

            PROBLEM:
            http://java.sun.com/j2se/1.5.0&lt;?Pub
               Caret>/docs/guide/plugin/developer_guide/index.html

            CORRECTION:
            Links into the docs should only be to j2se/1.5/docs
            rather than j2se/1.5.0/docs, as the latter links will
            break once 1.5.0 is EOL'd, while the former will continue
            to work for the latest 1.5.x version. (Note this URL
            is not in the original HTML page.)

        -------
        This bug would be easily facilitated by this separate request:

           Create a process for auto-generating both Linux (nroff)
           and Solaris (SGML) man pages from the HTML tool docs.
           This might involve first converting the HTML files to XHTML.

           If we convert from HTML to man pages, it will also involve two notes:

           1) Be sure NOT to convert pack200 and unpack200 from HTML to man pages,
              as the man pages are part of the pack200 specification.
              ###@###.### is the engineer.

           2) We would need to merge some information in the man pages that is not
              in the HTML, such as this in appletviewer.1. (This might be a reason
              to make the man pages the masters.)

             See attributes(5) for a description of the following attri-
             butes:

             ____________________________________________________________
            | ATTRIBUTE | |
            |_____________________________|_____________________________|
            | TYPE | ATTRIBUTE VALUE |
            |_____________________________|_____________________________|
            | Availability | SUNWj5dev |
            |_____________________________|_____________________________|

             java(1), jdb(1), attributes(5)

             For more information, see
             http://java.sun.com/j2se/1.5.0/docs/guide/plugin/developer_guide/index.html
             or search
                  java.sun.com



        Be sure NOT to convert pack200 and unpack200 from HTML to man pages,
        as the man pages are part of the pack200 specification.
        ###@###.### is the engineer.

          Attachments

            Issue Links

              Activity

                People

                • Assignee:
                  earmstrosunw Eric Armstrong (Inactive)
                  Reporter:
                  dkramersunw Douglas Kramer (Inactive)
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  0 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved:
                    Imported:
                    Indexed: