glassfish
  1. glassfish
  2. GLASSFISH-15470

every subcommand manual page include "asadmin-options" in the synopsis

    Details

    • Type: Improvement Improvement
    • Status: Reopened
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Affects Version/s: 3.1_b36
    • Fix Version/s: future release
    • Component/s: docs
    • Labels:
      None

      Description

      request that every subcommand manual page include "asadmin-options" in the synopsis with a note that information about the asadmin-options is on the asadmin manual page.

      Here is the motivation/use case email thread from users@glassfish.java.net as to why this is requested:

      http://java.net/projects/glassfish/lists/users/archive/2011-01/message/56

        Activity

        Hide
        Paul Davies added a comment -

        Defer to 3.2 for consideration. However, if the proposed fix is adopted, the synopsis would have to include asadmin <asadmin-options>, which reduces the prominence in the synopsis of the subcommand that is described in the man page.

        Show
        Paul Davies added a comment - Defer to 3.2 for consideration. However, if the proposed fix is adopted, the synopsis would have to include asadmin <asadmin-options>, which reduces the prominence in the synopsis of the subcommand that is described in the man page.
        Hide
        Paul Davies added a comment -

        After consideration, this RFE is declined. Adding this information would clutter the Synopsis and Options sections.

        Show
        Paul Davies added a comment - After consideration, this RFE is declined. Adding this information would clutter the Synopsis and Options sections.
        Hide
        Paul Davies added a comment -

        After further consideration and discussion, it seems that including all the related information is more important than not reducing the prominence in the synopsis of the subcommand that is described in the
        man page.

        The fix for this issue requires the following changes to the man page for each asadmin subcommand:

        • In Synopsis, prefix the subcommand with asadmin [asadmin-options] just like the usage statement.
        • In Options, add an explain for asadmin-options that cross-refers to asadmin(1M) and suggests running asadmin help as an alternative.
        • In See Also, move the cross-reference to asadmin(1M) to above the references to section 1 man pages.
        Show
        Paul Davies added a comment - After further consideration and discussion, it seems that including all the related information is more important than not reducing the prominence in the synopsis of the subcommand that is described in the man page. The fix for this issue requires the following changes to the man page for each asadmin subcommand: In Synopsis, prefix the subcommand with asadmin [asadmin-options] just like the usage statement. In Options, add an explain for asadmin-options that cross-refers to asadmin(1M) and suggests running asadmin help as an alternative. In See Also, move the cross-reference to asadmin(1M) to above the references to section 1 man pages.
        Hide
        Paul Davies added a comment -

        Too ambitious for a minor release such as 3.1.2. Aim to fix in 4.0

        Show
        Paul Davies added a comment - Too ambitious for a minor release such as 3.1.2. Aim to fix in 4.0

          People

          • Assignee:
            Paul Davies
            Reporter:
            jbenoit
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated: