-
Notifications
You must be signed in to change notification settings - Fork 21
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Example to play with new TRD stylesheets #41
base: main
Are you sure you want to change the base?
Conversation
5976dcb
to
9643e84
Compare
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.
I agree that the displayed title should not hyphenate on word wrap. 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.
It is my opinion that, yes, SUSE's logo should be shown even if it is the only one.
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. |
…ccessfully with daps
Thanks Terry for your help! I'll focus on the things that are still unclear or needs to be fleshed out.
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
Yes, that's not affected. You can still use hyphens, n-dashes, or m-dashes.
No, I mean the "Technical Reference Documentation" and "Getting Started" (the upper right corner). 🙂 |
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". 🙂 |
Okay, here is the current state: I would like to clarify some issues with you:
|
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. 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? |
Thanks Terry! Much appreciated.
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): Does that work for you?
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. 🙂 |
Thanks, Tom. Yes, the Summary looks good there. |
FYI
Did this, plus git checkout docteam-746-trd-xslt
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 plus ln -s /usr/home/bwgartner/Downloads/TRDSS/suse-xsl/trd /share/xml/docbook/stylesheet
Yet, with additions to docinfo, like 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, ... |
Pretty easy to mod those entries for RI/RC, as examples of the RI title -> Introductory Deployment of K3s RC title -> Layered Stack Deployment of K3s |
Ahh, this indicates that you don't have the latest DocBook package. The Mine is:
The latest package is available in OBS' Publishing repo. Add it to your list of repos with:
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. |
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 output
The culprit is that somehow it validates against the wrong DocBook version. It has to be version 5.2 as only there the Additionally, you did this:
That can be problematic. Better avoid that. Ok, some more ideas:
Hope this helps. |
Good clue (more info below) ... skipping output for now
Removed that approach
Again, am doing one of the RI files as prep for all those reference docs.
Yes, this was the glitch (in the DC file), so changed Now can create pdf/html/html --single files, yet still some more issues with daps...pdf command, see these during the successful run output ... and the output only has SUSE logo and title on 1st page.
No existence of ~/.config/daps
|
This PR demonstrates what meta data and other changes is needed to create the following TRD titlepage below.
Some questions:
<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. 🤔
Building with the new TRD stylesheets
If you want to replicate it, you can do the following:
Clone the SUSE stylesheet repo with:
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):Build your document(s) as usual, for example:
You could see some additional, weird messages. You can ignore these, they are debugging messages from the TRD stylesheets and will be removed later. 😉