document how to use adoc procedure correctly about doc-susemanager HOT 6 CLOSED

Copying in correspondence on this:

from doc-susemanager.

Hi Joseph and Karl!

Hoping you can help me work out what's going on here. I've attached
three screenshots:

1. In my text editor, note the two procedure headings. I can't see a
   difference in how they're formatted.

2. In the adoc preview tool, both headings have rendered correctly (and
   in exactly the same way).

3. In the generated PDF, the first heading is bold and inline, and the
   second has rendered correctly.

Any hints? I'm stumped. This is happening throughout the book.

Lana

from doc-susemanager.

Sep 25 18:58:46 Try moving the uppermost heading directly above the first list item
Sep 25 18:58:49 This is best practice.
Sep 25 18:58:55 oh, no intro para?
Sep 25 18:59:48 It may be a bug.
Sep 25 18:59:56 moment Ill look this up
Sep 25 19:00:30 it just seems odd to me that the preview tool renders it, but the build isn't
Sep 25 19:00:40 i was wondering if something was breaking in the xml conversion
Sep 25 19:00:53 It could also be the stylesheet
Sep 25 19:01:00 The adoc and xml are probably fine
Sep 25 19:01:09 most likely its caused by some weird xslt bug
Sep 25 19:01:51 What I would do, is make a subsection, intro, .procedure then list
Sep 25 19:01:59 I think that will clear it up for both procedures.
Sep 25 19:02:19 that's terrible form
Sep 25 19:02:29 oh right
Sep 25 19:02:30 (from a writing perspective, i mean)
Sep 25 19:02:32 sorry, skip the section
Sep 25 19:02:48 intro, then procedure.
Sep 25 19:02:56 yeah, that's the bit that i mean
Sep 25 19:03:05 Im not sure though, you have a parent section right?
Sep 25 19:03:08 So you could go
Sep 25 19:03:12 == Some title
Sep 25 19:03:15 text
Sep 25 19:03:18 if the intro is directly relevant to the procedure (not to the general concept), then it needs to go in there
Sep 25 19:03:28 === formula procedure
Sep 25 19:03:30 intro
Sep 25 19:03:35 .procedure
Sep 25 19:03:39 . list1
Sep 25 19:03:41 .list2
Sep 25 19:03:56 yeah, i get what you're saying
Sep 25 19:03:59 true, I get your point.
Sep 25 19:04:02 but it's about where that content is relevant
Sep 25 19:04:16 ok then just try this
Sep 25 19:04:19 .procedure
Sep 25 19:04:21 intro
Sep 25 19:04:25 with no linebreak
Sep 25 19:04:43 also, that ".Procedure:" formatting is just a sub-heading, right? it shouldn't matter whether it's prose or a dot point that comes after it
Sep 25 19:04:49 hrm, ok
Sep 25 19:04:51 i can try that
Sep 25 19:04:58 Im not sure, I have not run into this one :D
Sep 25 19:05:09 I can test it here if you point me to the correct document.
Sep 25 19:05:36 That is really weird behavior.
Sep 25 19:05:42 yeah, it's in the entire book
Sep 25 19:06:04 Maybe before that procedure, there is some unclosed block, or extra concat.
Sep 25 19:06:05 i noticed it in the install chapter too
Sep 25 19:06:24 https://github.com/SUSE/doc-susemanager/blob/develop/adoc/book_retail_getting_started.adoc
Sep 25 19:06:28 thanks
Sep 25 19:06:43 which chapter?
Sep 25 19:06:55 that example is specifically in the admin chapter
Sep 25 19:12:42 ah I think you are missing a + after the second note.
Sep 25 19:13:11 hrm, possibly. i tend to forget about them
Sep 25 19:13:17 that shouldn't break the heading, thoguh
Sep 25 19:13:19 though*
Sep 25 19:13:21 but I am not certain :D
Sep 25 19:13:29 It renders fine for me
Sep 25 19:13:34 Im thinking this is a stylesheet bug from doc team
Sep 25 19:15:02 try this formatting?
Sep 25 19:15:03 [steps]
Sep 25 19:15:03 .Procedure: Create a Hardware Type Group
Sep 25 19:15:40 Im not sure we need to add the procedure: part
Sep 25 19:15:48 I think if you use [steps] then a title
Sep 25 19:16:00 when we convert to xml steps is translated to a procedure.
Sep 25 19:16:13 huh, interesting idea
Sep 25 19:16:20 i'll give that a try
Sep 25 19:16:23 ok

Sep 25 19:38:35 The best thing you could do, would be to build the xml
Sep 25 19:39:10 so make book-to-set-suma
Sep 25 19:39:19 then check the generated xml
Sep 25 19:39:23 and see how the xml structure looks
Sep 25 19:39:37 that might tip us off :)
Sep 25 19:41:55 if both procedures look the same in the xml its an xslt bug.

from doc-susemanager.

OK, so I checked the generated XML, and it is definitely processing
differently based on the presence (or otherwise) of a para between the
title and the steps. So if you go straight to steps, it becomes an
orderedlist (which is being rendered correctly in the final), but the
addition of the para makes it a formalpara and starts the orderedlist
after the para (which is being rendered as inline bold).

To wit:

 <orderedlist numeration="arabic">

 <title>Procedure: Apply and configure the Saltboot Formula</title>

 <listitem><para>Open the details page for your new hardware group, and
 navigate to the <literal role="guimenu">Formulas</literal>
 tab.</para></listitem>

vs

 <formalpara>

 <title>Procedure: Create a Hardware Type Group</title>

 <para>For this procedure, you will require the system manufacturer
 name and product name for your terminal.</para>

 </formalpara>

 <orderedlist numeration="arabic">

 <listitem><para>Determine the hardware type group name.
 Prefix the name with <literal role="systemitem">HWTYPE:</literal>,
 followed by the system manufacturer name and product name, separated
 by a hyphen.</para></listitem>

Adding the [steps] notation before the title doesn't change this
behaviour, except for making the orderedlist declare a numeration style
of "steps", which then breaks the build (lol). Also, I couldn't find
anything online about usage for this notation, so it's possible I'm
doing it wrong. I've asked on a forum I'm on, though, so someone might
pop up with info for me on that.

So I think we're back to "don't put a paragraph between the Procedure
title and the steps", which is untenable from a writing perspective. You
simply must, in many cases, include information there. Can we adjust how
the XML is generated to amend this behaviour?

Lana

from doc-susemanager.

Update: I adjust all the procedures in the document to be third level headings (instead of using the dot notation). And it turns out that a colon in a heading causes a line break. So we have this delight now:

See: #217

from doc-susemanager.

I don't think there's anything further to do here. We have a workaround.

from doc-susemanager.