Example to play with new TRD stylesheets

[tomschr]

This PR demonstrates what meta data and other changes is needed to create the following TRD titlepage below.

Some questions:

• Do you need an "executive" summary on the second page?
• I've inserted a "don't hyphenate the title" rule. I suppose it's okay, right?
• Should the SUSE logo be shown if it's the only logo?
• I'm a bit unsure about the size and color of the two lines on the upper right edge. A bit hard to distinguish, right?
• I noticed we have two "Getting started" strings, one comes from the <subtitle> another from <meta name="type">. If we want to have an additional descriptive title, we should probably add other information in <subtitle> than a fixed strings. What do you think would be sufficient or useful?

Currently, I investigate why the logo at the bottom is so small. :thinking:

Building with the new TRD stylesheets

If you want to replicate it, you can do the following:

1. Clone the SUSE stylesheet repo with:

   $ git clone git@github.com:openSUSE/suse-xsl.git

2. Create a daps alias (you need to replace PATH_TO_YOUR_CLONE) in your current shell (or add it to ~/.bashrc if you prefer a more permanent solution):

   $ dapstrd () { local styleroot="$PATH_TO_YOUR_CLONE/trd/"; daps --styleroot=$styleroot $*; }

3. Build your document(s) as usual, for example:

   $ dapstrd -vv -d DC-gs_sles_jupyter-jupyterlab pdf Creating XML from AsciiDoc... [...] STYLEROOT: $PATH_TO_YOUR_CLONE/trd

   You could see some additional, weird messages. You can ignore these, they are debugging messages from the TRD stylesheets and will be removed later. :wink:

---

[tlssuse]

1. Do you need an "executive" summary on the second page?

I assume this is the paragraph (usually one sentence) we are including just above the disclaimer in the abstract. If so, then I think we should keep it. It would be nice if a blank line could appear between it and the disclaimer, though.

2. I've inserted a "don't hyphenate the title" rule. I suppose it's okay, right?

I agree that the displayed title should not hyphenate on word wrap. At the top of the second page, the title is repeated and it does appear to hyphenate on word wrap (e.g., "Server" became "Serv-er" with the "er" on the following line).

I did find a use for a hyphen in the title (see "SUSE Rancher 2.5: Edge Analytics with SUSE Rancher: Finance - Market Predictions"). Hopefully, we can still use hyphens in the title text.

3. Should the SUSE logo be shown if it's the only logo?

It is my opinion that, yes, SUSE's logo should be shown even if it is the only one.

4. I'm a bit unsure about the size and color of the two lines on the upper right edge. A bit hard to distinguish, right?

With the assumption that you mean the lines embedded with the lightbulb icon, I like them. Of course, my vision isn't what it used to be.

[tomschr]

Thanks Terry for your help!

I'll focus on the things that are still unclear or needs to be fleshed out.

1. Do you need an "executive" summary on the second page?

I assume this is the paragraph (usually one sentence) we are including just above the disclaimer in the abstract. If so, then I think we should keep it. It would be nice if a blank line could appear between it and the disclaimer, though.

Yes, I was more thinking about the markup. Should we add it in an ADoc file? How should it be converted to DocBook? Or should be just add it to the .docinfo file? I would prefer this, if it works for you. I need some attributes or other markup which I can match in my templates. For example:

<abstract role="...">  </abstract>

For role, it's up to us to define it. Could be summary or something else.

I did find a use for a hyphen in the title (see "SUSE Rancher 2.5: Edge Analytics with SUSE Rancher: Finance - Market Predictions"). Hopefully, we can still use hyphens in the title text.

Yes, that's not affected. You can still use hyphens, n-dashes, or m-dashes.

4. I'm a bit unsure about the size and color of the two lines on the upper right edge. A bit hard to distinguish, right?

With the assumption that you mean the lines embedded with the lightbulb icon, I like them. Of course, my vision isn't what it used to be.

No, I mean the "Technical Reference Documentation" and "Getting Started" (the upper right corner). :slightly_smiling_face: They have both the same color and size.

[tomschr]

I think, I found a solution:

This part is rendered as an invisible table. The blue border here is just for debugging reasons to show the space of each cell. It will be removed, of course. I was only concerned that I don't have enough space for the overly long string "Technical Reference Documentation". :slightly_smiling_face:

[tomschr]

Okay, here is the current state:

TRD Titlepage (click me)


I would like to clarify some issues with you:

1. Subtitle The "Getting Started" should be removed, right? The document type is already mentioned in the upper right corner. One option could be we use the subtitle for further differentiation, but not to add the doc type.

2. Shorten the title? Could we remove the "SUSE Linux Enterprise Server"? Couldn't we assume this is the default, because we are SUSE? :wink: It looks a bit redundant as we mention explicitly the product "SLES 15 SP4" already. I can imagine some benefits:

   • Better for SEO and Google Analytics
   • Easier to read on our documentation site
   • Benefits Twitter and OpenGraph cards when links are shared

[tlssuse]

Oh, I see what you mean about the two lines of text in the upper right with the SUSE logo on the left. I think making those larger would help.

For the executive summary, I am fine with it being in the docinfo file (that's where it is now). If we want to keep all the "content" defined in the adoc file, we could just define it as a variable there and reference it in the docinfo. Either way, we need a role: "summary" works for me, but if that is too generic, we could use "executivesummary" or "execsummary" or some other variation.

Yes, those are excellent suggestions to remove the document type from the subtitle and shorten the overall title. This makes sense for GS, where we are mainly focusing on the third-party components and the use case. For RI and RC, it may be more difficult to simplify those titles. What do you think, @bwgartner?

[tomschr]

Thanks Terry! Much appreciated.

For the executive summary, [...] we could use "executivesummary" or "execsummary" or some other variation.

I tried in the previous commit 9bdff93 to distinguish between a "Summary" and a "Disclaimer". After I did that, I realized the additional role attribute may not really be needed. The only distinction is the order and the title. This is how it looks like (screenshot without any borders, just the text width):

Verso page on TRD titlepage (click me)

 ---

Does that work for you?

This makes sense for GS, where we are mainly focusing on the third-party components and the use case. For RI and RC, it may be more difficult to simplify those titles.

Yes, it may not always be applicable. We have the same issues with the SBP titles. The titles can always be adapted, refined, or improved at any time. Probably you are already aware of that, just was a friendly reminder. It is maybe even not related to the new TRD stylesheets. :slightly_smiling_face:

[tlssuse]

Thanks, Tom. Yes, the Summary looks good there.

[bwgartner]

FYI

If you want to replicate it, you can do the following:

1. Clone the SUSE stylesheet repo with:
   ```
   $ git clone git@github.com:openSUSE/suse-xsl.git
   ```

Did this, plus

git checkout docteam-746-trd-xslt

2. Create a daps alias (you need to replace `PATH_TO_YOUR_CLONE`) in your current shell (or add it to `~/.bashrc` if you prefer a more permanent solution):
   ```
   $ dapstrd () { local styleroot="$PATH_TO_YOUR_CLONE/trd/"; daps --styleroot=$styleroot $*; }
   ```

Tried this, plus some simplified alternatives as well

daps --styleroot="/home/bwgartner/Downloads/TRDSS/suse-xsl/trd/" --force -vvvvv -d DC-kubernetes_ri_k3s-slemicro html --single

and also change DC STYLEROOT="/usr/share/xml/docbook/stylesheet/trd" FALLBCK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2021-ns"

plus

ln -s /usr/home/bwgartner/Downloads/TRDSS/suse-xsl/trd /share/xml/docbook/stylesheet daps --force -vvvvv -d DC-kubernetes_ri_k3s-slemicro html --single

3. Build your document(s) as usual, for example:
   ```
   $ dapstrd -vv -d DC-gs_sles_jupyter-jupyterlab pdf
      Creating XML from AsciiDoc...
      [...]
      STYLEROOT: $PATH_TO_YOUR_CLONE/trd
   ```

Yet, with additions to docinfo, like {trd}

And the {trd} variable added to SA_vars.adoc

The daps command fails with (even though xml file has the correct entry - Technical Reference Documentation

... error: element "meta" not allowed anywhere; expected the element end-tag, ...

[bwgartner]

Oh, I see what you mean about the two lines of text in the upper right with the SUSE logo on the left. I think making those larger would help.

For the executive summary, I am fine with it being in the docinfo file (that's where it is now). If we want to keep all the "content" defined in the adoc file, we could just define it as a variable there and reference it in the docinfo. Either way, we need a role: "summary" works for me, but if that is too generic, we could use "executivesummary" or "execsummary" or some other variation.

Yes, those are excellent suggestions to remove the document type from the subtitle and shorten the overall title. This makes sense for GS, where we are mainly focusing on the third-party components and the use case. For RI and RC, it may be more difficult to simplify those titles. What do you think, @bwgartner?

Pretty easy to mod those entries for RI/RC, as examples of the

RI title -> Introductory Deployment of K3s RI subtitle (was) -> Reference Implementation (but will move that to meta name="type")

RC title -> Layered Stack Deployment of K3s RC subtitle (was) -> Reference Configuration : Integrated with IHV (but can move RC portion to "type" and will leave "Integrated with IHV" portion as subtitle

[tomschr]

... error: element "meta" not allowed anywhere; expected the element end-tag, ...

Ahh, this indicates that you don't have the latest DocBook package. The <meta> tag was introduced in DocBook 5.2. If you get validation errors it means you have an older version of the schema.

Mine is:

$ rpm -q docbook_5
docbook_5-5.2b12-lp154.84.1.noarch

The latest package is available in OBS' Publishing repo. Add it to your list of repos with:

$ sudo zypper addrepo https://download.opensuse.org/repositories/Publishing/openSUSE_Leap_15.4/Publishing.repo

The example is shown for openSUSE Leap 15.4, change the version accordingly.

I'm preparing a DocBook 5.2 CR3 update which would be the most recent. Not sure if I can submit it today, but it will be available in the next days.

[bwgartner]

... error: element "meta" not allowed anywhere; expected the element end-tag, ...

Ahh, this indicates that you don't have the latest DocBook package. The <meta> tag was introduced in DocBook 5.2. If you get validation errors it means you have an older version of the schema.

Mine is:

$ rpm -q docbook_5
docbook_5-5.2b12-lp154.84.1.noarch

I had docbook_5-5.2b12-1.4.noarch, but even after installing docbook_5-5.2b12-84.7.noarch (on TW), still have same issue.

[tomschr]

I had docbook_5-5.2b12-1.4.noarch, but even after installing docbook_5-5.2b12-84.7.noarch (on TW), still have same issue.

Hmn, from the error message it looks like it doesn't validate against DocBook 5.2. Could you post the complete output? Here is mine for comparison, daps validate would be enough:

DAPS output

``` $ daps -vv -d DC-gs_sles_jupyter-jupyterlab validate Creating XML from AsciiDoc... /usr/bin/asciidoctor \ --attribute="idprefix=id-@" --attribute="idseparator=-@" --attribute env-daps=1 --attribute BP=1 --attribute GS=1 --attribute docdate=2022-08-30 --attribute=data-uri! --attribute=imagesdir! --attribute=attribute-missing=warn --attribute=daps-adoc-attributes="BP=1 GS=1 docdate=2022-08-30 env-daps=1" \ --backend=docbook5 --doctype=article \ --failure-level WARN --out-file=/home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter/build/.adoc/gs_sles_jupyter-jupyterlab.xml /home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter/adoc/gs_sles_jupyter-jupyterlab.adoc Successfully created XML file /home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter/build/.adoc/gs_sles_jupyter-jupyterlab.xml --------------- DAPS VERSION: 3.3.2 DOC_DIR: /home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter BUILD_DIR: /home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter/build DAPSROOT: /usr/share/daps DOCCONF: /home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter/DC-gs_sles_jupyter-jupyterlab BOOK: gs_sles_jupyter-jupyterlab DOCBOOK_VERSION: 5 DOCBOOK5_RNG: /usr/share/xml/docbook/schema/rng/5.2/docbookxi.rnc DBSTYLE_VERS: snapshot STYLEROOT: /usr/share/xml/docbook/stylesheet/nwalsh5/current STYLEROOT_VERS: Not available FB_STYLEROOT_VERS: Not available EPUB_CSS: HTML_CSS: PDF FORMATTER: fop FORMATTER VERSION: FOP Version 2.7 FORMATTER WRAPPER: /usr/share/daps/libexec/daps-fop FORMATTER CONFIG: /etc/daps/fop/fop-daps.xml MAKE_CMD: /usr/bin/make -f /usr/share/daps/make/selector.mk -j8 -s validate XSLTPROCESSOR: /usr/bin/xsltproc XML_CATALOG_FILES: /etc/xml/catalog --------------- Profiling /home/tom/repos/GH/SUSE/technical-reference-documentation/linux/start/jupyter/build/.adoc/gs_sles_jupyter-jupyterlab.xml Validating... Document is valid. Successfully validated profiled sources. ```

The culprit is that somehow it validates against the wrong DocBook version. It has to be version 5.2 as only there the <meta> element is available. Everything previous 5.2 will give you validation errors as you saw it.

Additionally, you did this:

ln -s /usr/home/bwgartner/Downloads/TRDSS/suse-xsl/trd /share/xml/docbook/stylesheet

That can be problematic. Better avoid that.

Ok, some more ideas:

• Using the correct DC file? I've only changed DC-gs_sles_jupyter-jupyterlab. Just to be sure, you have you used the same file, right? I'm asking, because in other files I didn't change it (which still might point to an older DocBook version).

• Broken XML catalog(s)? Another idea could be something related to the XML catalogs. They are responsible to rewrite URLs into local paths. This is needed to avoid accessing the Internet all the time. You can check if it works:

  $ xmlcatalog /etc/xml/catalog "http://docbook.org/xml/5.2/rng/docbookxi.rnc" file:///usr/share/xml/docbook/schema/rng/5.2/docbookxi.rnc

  If the command outputs an error, we know that this part is broken.

• User config You could look into ~/.config/daps/dapsrc and search for the DOCBOOK5_RNG_URI line.

Hope this helps.

[bwgartner]

I had docbook_5-5.2b12-1.4.noarch, but even after installing docbook_5-5.2b12-84.7.noarch (on TW), still have same issue.

Hmn, from the error message it looks like it doesn't validate against DocBook 5.2. Could you post the complete output? Here is mine for comparison, daps validate would be enough:

Good clue (more info below) ... skipping output for now

DAPS output The culprit is that somehow it validates against the wrong DocBook version. It has to be version 5.2 as only there the <meta> element is available. Everything previous 5.2 will give you validation errors as you saw it.

Additionally, you did this:

ln -s /usr/home/bwgartner/Downloads/TRDSS/suse-xsl/trd /share/xml/docbook/stylesheet

That can be problematic. Better avoid that.

Removed that approach

Ok, some more ideas:

• Using the correct DC file? I've only changed DC-gs_sles_jupyter-jupyterlab. Just to be sure, you have you used the same file, right? I'm asking, because in other files I didn't change it (which still might point to an older DocBook version).

Again, am doing one of the RI files as prep for all those reference docs.

• Broken XML catalog(s)? Another idea could be something related to the XML catalogs. They are responsible to rewrite URLs into local paths. This is needed to avoid accessing the Internet all the time. You can check if it works:

  $ xmlcatalog /etc/xml/catalog "http://docbook.org/xml/5.2/rng/docbookxi.rnc"
  file:///usr/share/xml/docbook/schema/rng/5.2/docbookxi.rnc

Yes, this was the glitch (in the DC file), so changed

DOCBOOK5_RNG_URI="http://docbook.org/xml/5.1/rng/docbookxi.rnc"

DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rnc"

Now can create pdf/html/html --single files, yet still some more issues

with daps...pdf command, see these during the successful run output

... Making portrait pages on A4 paper (210mmx297mm) [INFO ] page break | Creating a manual page break. If possible, limit this page break to these stylesheets by adding style="trd". If possible, limit this page break to this formatter by adding formatter="fop". (Source: within xml:id=id-legal-notice, at XPath=/book/chapter/pdfpagebreak) ... /usr/bin/build-classpath: Could not find avalon-framework Java extension for this JVM /usr/bin/build-classpath: error: Some specified jars were not found ...

and the output only has SUSE logo and title on 1st page.

If the command outputs an error, we know that this part is broken.

• User config You could look into ~/.config/daps/dapsrc and search for the DOCBOOK5_RNG_URI line.

No existence of ~/.config/daps

Hope this helps.