Uploaded image for project: 'OpenDJ'
  1. OpenDJ
  2. OPENDJ-7374

Make sure the man page example output matches current server output

    Details

    • Type: Task
    • Status: Dev backlog
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: 7.0.0
    • Fix Version/s: None
    • Component/s: documentation, tools
    • Labels:
      None

      Description

      A number of the DS reference manual pages generated during the server build include example sections. See the files named *-example.xml in https://stash.forgerock.org/projects/OPENDJ/repos/opendj/browse/opendj-doc-generated-ref/src/main/docbkx/man-pages .

      Some, but not all, of the example sections simply repeat information that is already covered in the hand-written docs, opendj-docs, and it might be best to remove these. If the output is shown in opendj-docs it's probably tested every build, whereas the output in the man page sections seems often to be missed by developers when they update the command output.

      There are a few pages with example sections worth preserving, however. This includes the sections for the *rate tools, such as https://stash.forgerock.org/projects/OPENDJ/repos/opendj/browse/opendj-doc-generated-ref/src/main/docbkx/man-pages/addrate-examples.xml , where the example section also explains how to read the output.

      Acceptance criteria

      • Remove untested examples that duplicate information elsewhere in the docs.
      • Retain useful examples that do not duplicate the docs.
      • Consider adding tests for remaining examples so developers do not have to remember they're there.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              Mark Mark Craig
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: