lists vs procedures WAS: Patch for Kubuntu Desktop Guide: Games Section

[Brian Shumate]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matt,

I don't find this behavior to be the case, in Yelp anyway.

I generated a sample procedure, and grafted it into an existing  
section of the Server Guide to test this behavior, and I am not  
seeing the reference to my procedure as you've explained.

I pasted the following procedure code into my working copy of the  
introduction.xml for the Server Guide, and no reference occurs  
anywhere regarding the procedure, with the exception of the procedure  
title on that specific page of the guide, and without the  "Procedure  
n:" preceding it.  From my observation, it would appear this tag  
would work without any of the adverse effects you're concerned  
about.  I would invite others to do their own testing, as mine was  
hurried, and I could have overlooked something.

Here's what I used to test, in case I've made a mistake somewhere, or  
if anyone else wishes to paste this in and test the output :

<procedure>
<title>Testing Procedure Tag Behavior</title>
<para>Perform the following steps in order to realize a procedure  
behavior in Yelp.</para>
<step performance="required">
<para>
Open your preferred editor, (without starting an editor war) and  
begin editing some Docbook XML such as the raw code which generated  
this procedure.
</para>
<para>Now, you are ready to enter the procedure realm.  Make sure to  
correctly observe the syntax.</para>
<substeps>
<step performance="optional">
<para>Enter some commentary.</para>
</step>
<step performance="required">
<para>Close all tags.</para>
</step>
</substeps>
</step>
<step performance="required">
<para>Save your file.  Save early, save often! ;-)
</para>
</step>
</procedure>


Peace,

Brian Shumate
GPG: 0x441E06C0


On Feb 15, 2006, at 2:41 AM, Matthew East wrote:

> Brian Burger <blurdesign <at> gmail.com> writes:
>
>>
>> On 2/14/06, Jeff Schering <jeffschering <at> gmail.com> wrote:
>>> On 2/14/06, Brian Burger <blurdesign <at> gmail.com> wrote:
>>>> Actually, in the Ubuntu Desktop Guide, we/I replaced the qandasets
>>>> with sectX tags (sect1, sect2, etc), and mdke has been replacing  
>>>> our
>>>> orderedlists with itemizedlists (going from numbered lists to just
>>>> bullet points, in other words...)
>>>>
>>> Procedures such as those found in the common tasks section of the
>>> desktop starter guide need to be numbered. Bulleted lists are not  
>>> used
>>> in procedure steps, and only when the order of list items is not
>>> important.
>>>
>>> Both the orderedlist tag and the itemizedlist tags are not the  
>>> correct
>>> tags for procedure steps. Instead, we should be using the procedure
>>> tag. See  http://www.docbook.org/tdg/en/html/procedure.html and  
>>> also,
>>> from the KDE Docbook Authors Guide:
>>> http://i18n.kde.org/doc/markup/lists.html
>>
>> Thanks, Jeff. I'm still learning DocBook/XML by hacking other  
>> people's
>> code, and the semantic markup of it still trips me up sometimes.
>>
>> Links bookmarked, and I'll start changing UDG over later this week.
>
> Actually I think we should look carefully at this. While procedure  
> tags may
> technically be the correct tag to apply, I think the output will be  
> totally
> rubbish. Using <procedure><title>Example section in guide</title>  
> will produce:
>
> Procedure 1: Example section in guide.
>
> That means that everywhere in the guide we'll have:
>
> Procedure 24: Connecting to the Internet
> Procedure 25: Browsing Network Computers
> Procedure 26: Email
> Procedure 27: World Wide Web
>
> (as an example).
>
> I really think that doing this would be a blow against usability  
> and readability
> of the guide. I prefer the bulleted ists because they display  
> better and the
> numbered seem to me to make it more difficult to read. However if  
> people prefer
> the look of the numbered lists, we can revert to those. I'm really  
> not keen on
> having the word "procedure" all over the guide. Tell me if I've  
> misunderstood
> how the tag works.
>
> What do others think?
>
> Matt
>
>
> -- 
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

-----BEGIN PGP SIGNATURE-----

iD8DBQFD81xi43QdCUQeBsARAgLqAJ9+gxPxTr4zBFPq23HiaQQknvFTVACg3Eo4
u30jEs7rCIqlELce5i35PcE=
=4eCO
-----END PGP SIGNATURE-----