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

["Colin Shapiro" <cmshapiro@gmail.com>]

On 5/1/07, David O'Brien <david.obrien@redhat.com> wrote:

Hi Colin
How did you manage to nest the markup? Don't you need to escape the
double quotes around "protocol" somehow? My parser is complaining:

Sorry, my example had a typo.  I meant for the nested quotes to be single quotes:

<!ENTITY tcp "<systemitem class='protocol'>TCP</systemitem>">

Alternatively, you can swap the double and single quotes around:

<!ENTITY tcp '<systemitem class="protocol">TCP</systemitem>'>

Colin

START: test-en-US Wed May  2 11:47:38 EST 2007
tmp/en-US/xml/Release_Notes.ent:2: parser error : xmlParseEntityDecl:
entity httpd not terminated
<!ENTITY httpd "<systemitem class="daemon">httpd</systemitem>">

thanks a lot
David


Colin Shapiro wrote:
> 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
>>
>>
>>
>


--
/David