Re: recommend a tag for user accounts in computer documentation?

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:

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=&quot;daemon&quot;>httpd</systemitem>&quot;>

thanks a lot
David


Colin Shapiro wrote:
>; Yeah, a minimalist approach has its benefits.&nbsp; 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=&quot;protocol&quot;>&lt;acronym&gt;TCP</acronym>&lt;/systemitem>&quot;>
&gt; <para&gt;The protocol &tcp; is a communications protocol...</para&gt;
>
&gt; 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. &nbsp;It works
&gt; well for my needs.
>;
> Colin
>
> On 4/30/07, David O'Brien < david.obrienredhat.com">david.obrienredhat.com> wrote:
>;>
>&gt; Colin Shapiro wrote:
&gt;> > Yes, that works as well.
>> >
>&gt; > There are several choices here, and what you actually use will
>&gt; depend on
>>; > the
>&gt; > context and what you want to do with the document.&nbsp; For example, if all
>> you
>&gt; > want to convey is that the item is a username, then this will probably
&gt;> > suffice:
&gt;> >
>&gt; > <systemitem class=&quot;username&quot;>root</systemitem>
>> >
>&gt; > However, if you want to convey that the item is a username *and*
>> that it
>>; is
>>; > user input, as in "Enter the username 'root&#39; and log in", you may want
>;> to
>>; > use one of the following instead:
&gt;> >
>&gt; > <userinput role=";username&quot;>root</userinput>
&gt;> > <userinput><systemitem class=&quot;username&quot;>root</systemitem>&lt;/userinput>
&gt;> >
>&gt; > This is a problem that I frequently have with DocBook; there are
>&gt; 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.
>&gt; >
>&gt; > Colin
>> >
>&gt; > On 4/30/07, Skopik Pavel < Pavel.Skopikaipsafe.cz"> Pavel.Skopikaipsafe.cz> wrote:
>;> >>
&gt;> >>
&gt;> >>
&gt;> >> You can also use „systemitem" element which has built-in class
>> >> „username&quot;.
&gt;> >>
&gt;> >>
&gt;> >>
&gt;> >> pavel
>> >>
&gt;> >
>&gt; 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,
&gt;> avoiding nesting/multiple tags as much as I can. Case in point? TCP.
>;> It's a protocol <systemitem class=&quot;protocol&quot;> but also an abbreviation
>> <abbrev>. I'm leaning away from using <abbrev> because there is so much
>&gt; of it in computer documentation. Same goes for <acronym>.
&gt;>
>> cheers
>;>
>&gt; --
>>; /David
>;>
>&gt;
>>;
>


--
/David