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

toolkit: Refactor document structures into builders and description files

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Won't Fix
    • P4
    • 9
    • 1.4.0
    • tools

    Description

      Goal is to further increase the shared code between the standard doclet and
      MIF doclet, reducing their discrepancies, making the doclets smaller and
      simpler. This would also make it easier to generate new doclets.
      We could refactor the code further in two ways:

      - Abstract out document structures such as headings, paragraphs, bulleted lists,
        indented paragraphs, tables, code paragraphs, and so forth into builders in
        the toolkit shared code. The actual markup for these would be provided by the
        individual doclets, including the formatting such as fonts, colors,
        alignment, positioning, margins, amount of indent, and so forth.

      - Abstract out the order of elements on a page into page description files
        that are markup-independent. These then become shared code that
        is part of the toolkit. A set of page description files could be used
        by any doclet. This would ensure that the order is identical for
        different doclets, and would enable easy modification of the output
        when Javadoc is run. These files would likely be in XML.

      When generating a class page, for instance, the HTML doclet would specify
      a particular set of description files, then call the toolkit for each page
      element. It might call the toolkit for a table version of the member
      summary, and the toolkit would in turn ask the HTML doclet for the markup
      to start a table, start a row, start a cell, etc.

      Taken to the limit, the individual doclets (HTML, MIF, RTF) are simply drivers
      that specify a set of description files and contain markup definitions
      (e.g., for HTML, paragraph start is <P>). James Gosling is a big proponent
      of this approach.

      The main descriptions files would be:

      Main pages:
         Overview Description File
         Package Description File
         Class Description File
         PackageTree Description File
         ClassTree Description File
         PackageUse Description File
         ClassUse DescriptionFile
         Deprecated DescriptionFile
         SerializedForm Description File
         ConstantValues Description File
         IndexSingle Description File
         IndexSplit Description File

      Frames:
         Frameset Description File
         Overview-Frame Description File
         Package-Frame Description File
         AllClasses-Frame Description File

      For the MIF Doclet, there would be additional files:
         Book File (effectively, today's XML Book File)
         TitlePage Description File
         AlmanacLegend Description File
         Almanac Description File
         CrossReference Description File

      Attachments

        Activity

          People

            bpatel Bhavesh Patel (Inactive)
            dkramersunw Douglas Kramer (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: