Doctypes Maven Plugin

Space shortcuts

Page tree

Versions Compared

Old Version 12

changes.mady.by.user Robert Reiner

Saved on

compared with

New Version 13

changes.mady.by.user Robert Reiner

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleDetails

Here are some aspects of using the doctype XSD to specify doctype descriptors.

Section
titleBase Template

Base templates provide standard properties and sections. Typically documents should be based on the standard template.

Code Block
languagexml
<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  id="my-doctype"
  base-template="standard">
...
</doctype>

The following templates are provided.

Definition List


standardProvides the standard properties and sections.
typeProvides properties and sections required by categorizing document types.
emptyProvides no properties and sections.



Note Box

The

System Link
filedoctype-doc.html
system-typesite
checktrue
labelDoctype XSD
lists all valid types. Currently users cannot define their own templates without getting hands on the source code.



Section
titleProvide Type

If the attribute provide-type of the doctype element is set to the name of a type template, a type doctype based on that type will be generated. This type document is used as a doctype-specific category to organize document instances for that type.

Example Box

If you have a doctype resource with this property set to 'true', an additional doctype named resource-type will be generated. Types for resources may be 'Article', 'Website', or 'Podcast'.

Two values are currently allowed: none for providing no type (default), and standard-type.

Code Block
languagexml
<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  ...
  provide-type="standard-type"
  ...>



Section
titleHas Homepage

Signals whether or not the doctype has its own homepage. This defaults to true, so there is a homepage for the doctype.

Code Block
languagexml
<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  ...
  has-homepage="false"
  ...>


Note Box
titleWizard Configuration

If there is no homepage, the generated wizard for the doctype should usually provide means to send a new page to its default location.

Use the following wizard configuration to omit the Target Homepage element.

Code Block
languagexml
<wizard template="no-homepage" />




Section
titleRelated Doctypes

The related-doctypes element within the doctype element contains a list of doctype IDs. Links to the mentioned doctypes are added to index pages and home pages as references.

Code Block
languagexml
titleExample with related-doctypes
<related-doctypes>
  <id>affected-users</id>
  <id>damage-potential</id>
  <id>discoverability</id>
  <id>exploitability</id>
  <id>mitigation-level</id>
  <id>reproducibility</id>
  <id>threat-type</id>
</related-doctypes>



Section
titleCategory

Reference one of the categories defined with the add-on descriptor.

Code Block
languagexml
<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  ...
  category="threat-aspect">



Section
titleMetadata

A doctype may provide additional metadata.

Code Block
languagexml
<metadata>
  <property key="projectdoc.doctype.common.is-a">aspect</property>
</metadata>

Key and value of a metadata entry must be character sequence.

Metadata is added as artificial properties to a projectdoc document.

Version Box
titleSince projectdoc Toolbox 4.5
since4.5

The key projectdoc-materialize allows to define default materializations of document properties.

Code Block
languagexml
  <metadata>
    <property key="projectdoc-materialize">projectdoc>
      projectdoc.doctype.common.tags-&gt;projectdoc.doctype.common.type, 
      projectdoc.doctype.common.type-&gt;projectdoc.doctype.common.sortKey<sortKey
    </property>
  </metadata>




Section
titleProperty Value

The contents of the property value element may contain

  • arbitrary XML within an xml element.

  • a macro definition.

  • a placeholder.
Section
titleXML


Code Block
languagexml
<property key="projectdoc.doctype.common.iteration">
  <value>
    <xml><![CDATA[<ac:structured-macro ac:name="projectdoc-iteration">
  <ac:parameter ac:name="value">production</ac:parameter>
</ac:structured-macro>]]></xml>
  </value>
</property>



Section
titleMacro


Code Block
languagexml
<property key="projectdoc.doctype.common.type">
  <value>
    <macro name="projectdoc-name-list">
      <param name="doctype">security-view-type</param>
      <param name="property" key="projectdoc.doctype.common.type" />
      <param name="render-no-hits-as-blank">true</param>
    </macro>
  </value>
  ...
</property>



Section
titlePlaceholder


Code Block
languagexml
<property key="projectdoc.doctype.security-view.service">
  <value>
    <placeholder key="projectdoc.doctype.security-view.service.placeholder" />
  </value>
  ...
</property>

Since this is the default configuration, you may omit the value element completely.

Code Block
languagexml
<property key="projectdoc.doctype.security-view.service">
  ...
</property>




Section
titleSection


Section
titleDoctype Description

A section may override the description section's placeholder. This is helpful to provide page authors with specific help on what to add to the description section's body.

Code Block
languagexml
<section key="projectdoc.doctype.common.description">
  <resource-bundle>
    <l10n>
      <description>
        Provide a view on a service from the security perspective. Describe
        the service briefly and link to
        it for further information.
      </description>
    </l10n>
    <l10n locale="de">
      <description>
        Erstellen Sie eine Sicht auf einen Service aus der
        Sicherheitsperspektive. Halten Sie die
        Beschreibung kurz und
        fokussieren Sie auf die Belange der Sicherheit. Verweisen Sie auf die
        Servicedokumentation für weitere Informationen.
      </description>
    </l10n>
  </resource-bundle>
</section>


Note Box

This works for all sections that only provide a placeholder text. The key may be a local internationalization (I18N) key.

The following example shows how the common description (provided by the standard doctype), the common summary (not provided by the standard doctype), and a doctype specific sections is specified. All three will render its placeholder text in the section body.

Code Block
languagexml
  <sections>
    <section key="projectdoc.doctype.common.description">
      <resource-bundle>
        <l10n>
          <description>
           Describe the reason why this step is valuable and what readers may
           learn from reading this document.
          </description>
        </l10n>
        <l10n locale="de">
          <description>
            Beschreiben Sie, warum dieser Schritt wichtig ist und was Leser
            dadurch lernen können.
          </description>
        </l10n>
      </resource-bundle>
    </section>
    <section key="projectdoc.doctype.common.summary">
      <resource-bundle>
        <l10n>
          <description>
           Describe what is the result of taking this step or what can be
           learned after finishing this step.
          </description>
        </l10n>
        <l10n locale="de">
          <description>
            Beschreiben Sie zusammenfassend, was die Erkenntnisse aus diesem
            Schritt sind oder was das Ergebnis dieses Schritts ist.
          </description>
        </l10n>
      </resource-bundle>
    </section>
    <section key="projectdoc.doctype.step.actions">
      <resource-bundle>
        <l10n>
          <name>Actions</name>
          <description>
            Describe what has actually been done to execute this step. This may
            include screenshots and more than one step. If there are too many
            steps that need to be explained, add additional step documents as
            children to this document.
          </description>
        </l10n>
        <l10n locale="de">
          <description>
            Beschreiben Sie die Durchführung dieses Schritts in einzelnen
            Aktionen. Dies kann Screenshots beinhalten. Wenn die einzelnen
            Aktion noch immer sehr komplex ist und einer ausführlichen
            Erläuterung bedarf, kü6nnen sie die einzelnen Schritte auch in
            eigenen Teildokumenten beschreiben und diesem Dokument als Kinder
            anfügen.
          </description>
        </l10n>
      </resource-bundle>
    </section>
  </sections>




Section
titleXML

The section allows to specify an arbitrary document part in the storage XML format.

Note Box

Please note that the section marco needs to be specified. Technically you could add elements that are no section macros.


Code Block
languagexml
<section key="projectdoc.doctype.security-control.mitigation-strategies">
  <xml><![CDATA[<ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n 
		  at:key="projectdoc.doctype.security-control.mitigation-strategies"/></ac:parameter>
        <ac:parameter ac:name="intro-text"><at:i18n 
		  at:key="projectdoc.doctype.security-control.mitigation-strategies.intro"/></ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:name="projectdoc-display-table">
            <ac:parameter ac:name="doctype">mitigation-strategy</ac:parameter>
            <ac:parameter ac:name="render-no-hits-as-blank">true</ac:parameter>
            <ac:parameter ac:name="restrict-to-immediate-children">true</ac:parameter>
          </ac:structured-macro>
        </ac:rich-text-body>
      </ac:structured-macro>]]></xml>
  <resource-bundle>
    <l10n>
      <name>Mitigation Strategies</name>
      <intro>List of strategies to mitigate the impact of a potential threat.</intro>
    </l10n>
    <l10n locale="de">
      <name>Strategien zur Abschwächung</name>
      <intro>Liste Vorgehensweisen, um die Wirkung möglicher Bedrohungen abzuschwächen.</intro>
    </l10n>
  </resource-bundle>
</section>


Tip Box

If the XML snippet contains additional I18N keys, use the label element to provide localized information for them.

Code Block
<resource-bundle prefix="projectdoc.doctype.configuration-item">
  <l10n>
    <name>Dependencies</name>
    <label key="list-of-documentation-assets">Documentation Assets</label>
    <label key="list-of-documentation-assets.intro">This configuration item is 
                          described in the following documentation assets.</label>
    ...

Note that the prefix specified with the resource-bundle element is prepended to each label element's key attribute value. So in the XML snippet of this example the following keys are used:

  • projectdoc.doctype.configuration-item.list-of-documentation-assets
  • projectdoc.doctype.configuration-item.list-of-documentation-assets.intro
Use this approach if you happen to require nested sections.




...

About

This site is maintained by smartics.

Imprint / Impressum

Data Privacy / Datenschutz 

End User License Agreement (EULA)


To get in touch please send us an e-mail!

smartics email

Keep up-to-date!

Read our

smartics Blog

Follow us on

Twitter YouTube Prezi

Find us on

Bitbucket GitHub Atlassian Marketplace

Powered by




© 2001-2023 smartics - Kronseder & Reiner GmbH