Question: Have you considered adding output classes to the generated DITA

kirkilj commented 2 years ago

Hi Jason,

Have you considered adding outputclasses to the generated DITA so the semantics of the JavaDoc can be styled as needed? We could easily add those, but it might make your plugin more customizable.

Syncrosoft's recent OpenAPI to DITA converter uses this approach:

<topic id="getAllDashboard" outputclass="openapi-operation">
      <title outputclass="openapi-operation-title openapi-method-get">
        <ph id="getAllDashboard-operationName">
          <ph outputclass="openapi-operation-method-get">GET</ph>
          <ph outputclass="openapi-operation-path">/api/v1/packages/{packageId}/dashboards</ph>
        </ph>
      </title>
      <shortdesc>
        <ph id="getAllDashboard-shortdesc-ph">Retrieves all supported and available package dashboards</ph>
      </shortdesc>
      <body>
        <section outputclass="openapi-parameters">
          <title>Parameters</title>
          <dl outputclass="openapi-parameters-list">
            <dlentry id="packageId-path" outputclass="openapi-parameter">
              <dt outputclass="openapi-parameter-name-in">
                <ph outputclass="openapi-parameter-name">packageId</ph>
                <ph outputclass="openapi-parameter-in">(path)</ph>
              </dt>
              <dd>
                <dl outputclass="openapi-schema-values">
                  <dlentry>
                    <dt>type</dt>
                    <dd>string</dd>
                  </dlentry>
                </dl>

jason-fox commented 2 years ago

With a format="javadoc <topic>, the transform already places outputclass="java" on the <body> of each topic. That is sufficient to add code highlighting using the Prism.js plugin which works out Java semantics.

The PDF output looks something like this:

Obviously you can tweak the colours as necessary e.g. here

kirkilj commented 2 years ago

That's handy, but I'd still prefer to retain a semantic trail for other future possible needs beyond formatting.

jason-fox commented 2 years ago

If you want to add the semantics directly to the JavaDoc DITA just run with both the JavaDoc and PrismJS plugins and run the normalize transform:

./dita -f dita -i <input>.ditamap  -Dprismjs.highlightable=true

The result is something like this:

<row>
  <entry colname="col1" align="left">
    <codeph outputclass="language-java">
      <ph outputclass="token keyword">static</ph>
      <ph outputclass="token class-name">Effect</ph>
    </codeph>
  </entry>
  <entry colname="col2" align="left">
    <codeph outputclass="language-java">
      <xref format="dita" scope="local" type="table" href="#org.casbin.jcasbin.effect.Effect/methods_valueOf">valueOf</xref>
      <ph outputclass="token punctuation">(</ph>java
      <ph outputclass="token punctuation">.</ph>lang
      <ph outputclass="token punctuation">.</ph>
      <ph outputclass="token class-name">String</ph> name
      <ph outputclass="token punctuation">)</ph>
    </codeph>Returns the enum constant of this type with the specified name.
  </entry>
</row>

kirkilj commented 2 years ago

Great idea. I've asked the writer to have their R&D peers generate the XML from the xmldoclet so I have something of theirs to play with.

jason-fox / fox.jason.passthrough.javadoc

Question: Have you considered adding output classes to the generated DITA #1