chentex / caasp-release-notes Goto Github PK

Want to help? We love to hear that! Below are a few hints to guide you.

The final version for the product is build in the SUSE Build Service.

For validation and test purposes follow the steps below:

1. Install the DocBook Authoring and Publishing Suite (daps) package from the Documentation:Tools openSUSE Build Service project.

2. Use the make to build all required documents. For a single HTML document, for example make single-html.

The GitHub/GitLab preview mode is handy but comes with a couple of snags compared to the build of the release notes that is used for the SUSE Web site:

• GitHub/GitLab will simply render a preview of a single *.adoc file using AsciiDoctor’s built-in HTML conversion. GitHub/GitLab previews do not support embedding one AsciiDoc file in another, you can only use links between them.

• The SUSE Web site build combines multiple *.adoc files into a single HTML output file. It is based on AsciiDoctor’s AsciiDoc-to-DocBook-XML conversion, the result of which is then further converted into HTML/PDF using DAPS and the DocBook XSL stylesheets.

For this reason, the central file adoc/MAIN.release-notes.adoc contains somewhat unsightly ifdef/ifndef blocks that check whether the file is displayed in the GitHub/GitLab preview, switching between using links to other files for GitHub/GitLab and include:: statement in all other cases.

The issue of not being able to embed other AsciiDoc files when using the GitHub/GitLab preview also affects the "attribute entries" file adoc/entities.adoc. Attribute entries allow easily referencing text used multiple (similar to entities in XML). Hence, for the GitHub/GitLab preview, each file contains a copy of the entire attribute entry file at the top. When updating attribute entries, always make sure to:

1. Edit adoc/entities.adoc first (these are used for the regular build)

2. Run make update-entries to update the dependent attribute entries in each of the *.adoc files (these are used for GitHub/GitLab previews).

The website is automatically updated when we release a new version of the release-notes-caasp package as maintenance update.