OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] FW: Re: [docbook] recommend a tag for user accounts in computer documentation?


Yeah, a minimalist approach has its benefits.  I've tried to take the same approach, however I sometimes later realize that I could have used the extra markup that I chose to omit.

Now, I do things a little more verbosely, but use many entities.to save time.  For example, I'd probably mark up TCP like this:

<!ENTITY tcp "<systemitem class="protocol"><acronym>TCP</acronym></systemitem>">
<para>The protocol &tcp; is a communications protocol...</para>

My file containing these common entity definitions is shared among documents, so if I want to change the way a term is marked up, I can do so across all applicable docs.  And since the bulk of the extra markup is removed from the main document, the source files are kept relatively small.

Just something to think about if you're interested in trying it.  It works well for my needs.

Colin

On 4/30/07, David O'Brien < david.obrien@redhat.com> wrote:
Colin Shapiro wrote:
> Yes, that works as well.
>
> There are several choices here, and what you actually use will depend on
> the
> context and what you want to do with the document.  For example, if all you
> want to convey is that the item is a username, then this will probably
> suffice:
>
> <systemitem class="username">root</systemitem>
>
> However, if you want to convey that the item is a username *and* that it is
> user input, as in "Enter the username 'root' and log in", you may want to
> use one of the following instead:
>
> <userinput role="username">root</userinput>
> <userinput><systemitem class="username">root</systemitem></userinput>
>
> This is a problem that I frequently have with DocBook; there are often a
> number of ways to do something, and I have to think about what I really
> want
> to convey with the markup before I can figure out the approach to use.
>
> Colin
>
> On 4/30/07, Skopik Pavel <Pavel.Skopik@aipsafe.cz > wrote:
>>
>>
>>
>> You can also use „systemitem" element which has built-in class
>> „username".
>>
>>
>>
>> pavel
>>
>
Yes, I have the same trouble in other areas, where something should be
tagged as X but it's being used in a different context so it should also
(or instead) be tagged as Y.

I tend to take a minimalist or simplistic approach and tag by context,
avoiding nesting/multiple tags as much as I can. Case in point? TCP.
It's a protocol <systemitem class="protocol"> but also an abbreviation
<abbrev>. I'm leaning away from using <abbrev> because there is so much
of it in computer documentation. Same goes for <acronym>.

cheers

--
/David





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]