The move to custom XML

Timothy Bauscher timothy at linuxfromscratch.org
Mon May 19 18:27:13 PDT 2003


On Tue, May 20, 2003 at 01:44:48AM +0200, Matthias Benkmann wrote:
> > 1. acknowledgements.xml
> > 
> > <sect type="page" id="ch01-acknowledgments"
> > file="acknowledgements.html"><title>Acknowledgments</title>
> 
> I don't like the use of attributes. Attributes are completely unnecessary
> when doing custom XML and avoiding them makes XSLT rules simpler, because
> you don't have to ask yourself "Hmm. Was 'title' an attribute of sect or
> an extra tag?"

Then <sect type="page"> can be substituted with <page> and type="package"
with <package>. Okay.

> I never use attributes and I don't miss them.

The file attribute can be eliminated altogether, as has been
suggested. But what about id's? Would you rather do something
like this?

<page>
  <id>ch01-acknowledgements</id>
  <title>Acknowledgements</title>
  ...
</page>

> Avoiding attributes also allows me to use my  foo{...}  shorthand as in
> 
> section{  title{Some title}
>   p{
>     This is a keyword{paragraph}.
>   }
> }
> 
> which IMHO makes it much easier to write XML. I think this shorthand (or
> something else if someone has an idea) is something that should be
> considered for the book. A lot of people want to contribute who don't work
> much with XML and who don't have fancy XML editors that offer tag-matching
> etc. For these people the shorthand form would be much easier to work
> with. BTW, the current version of my brace2xml supports automatic
> paragraph insertion. I got tired of inserting p-tags everywhere. I much
> prefer the TeX style where an empty line signifies a paragraph break as in
> 
> section{  title{Some title}
>   
>     This is a paragraph.
> 
>     This is another paragraph.
> 
> }

Clean.

> > <list type="itemized" heading="Contributions">
> 
> If you do not rise above the structures you know from Docbook/HTML you're
> wasting much of the potential of custom XML.

Agreed. I had trouble breaking out of my docbook experience and
could feel it's presence in the not-so-new work.

> <list type="itemized"> is not good markup. It refers in a certain
> degree to presentation and says little about the content. I would
> write (in shorthand, preferring CAPS for tags)
> 
> CONTRIBUTIONS{
>   THANKSTO{ 
>     PERSON{Gerard Beekmans MAIL{gerard}} for leading the LFS project }
> }

Nice.

> The MAIL{gerard} would be resolved via another file. Links should *never*
> be embedded in the main document. It's a maintenance horror. I use a
> links.xml file like this
> 
> links{
>   link{ name{ LFShome }  URL{http://www.linuxfromscratch.org} }
>   link{ name{ news }     URL{news.html}              }
>   link{ name{ index }    URL{index.html}             }
>   link{ name{ validate } URL{http://validator.w3.org/check/referer} }
> 
>   mail{ name{ gerard }  URL{gerard at linuxfromscratch.org}       }
> }

Excellent idea.

> > <input><command>./configure --prefix=/usr</command>
> > 
> > <exp>
> 
> Be verbose, write "explanation". A lot of people will read this who have
> no idea what "exp" is supposed to mean.

Okay.

> > <output><text>
> 
> <text>? Seldom have I seen a less useful tag-name. Everything in the book
> is text. What KIND of text are we dealing with here? How about
> "programoutput" or "commandoutput". Doesn't sound nice but is more
> descriptive and useful.

Okay.

> > 3. File creation
> > 
> > <input><cat>$LFS/etc/group</cat>
> 
> This is a well-meant attempt at abstraction but ask yourself: If you want
> to abstract away the fact that we're using the cat command to create the
> file, is it a good idea to name the tag "<cat>" ?

Good point. <file>, <filename> would make more sense.

> If you want to have this level of abstraction (I think it causes more
> trouble than it's worth and would insert the cat-command itself), you
> should do something like
> 
> FILECREATION{ PATH{$LFS/etc/group}
> CONTENT{
> root:x:0:
> bin:x:1:
> ......
> }
> }

Nice.

> Personally, I would not include the file contents in the XML document. I
> would keep it separate (in a file called, what a surprise "group") and use
> a reference mechanism as described for LINK above to include it during the
> XSLT transformation. Among other things, this avoids whitespace issues.
> It might also be a good idea to put the PATH into this reference file as
> well instead of hardcoding it into the main text.

Okay.

> > 4. Emphasis
> > 
> > <warning>Don't forget to install Emacs</warning>
> 
> If you can, be more specific than just "<warning>". What's the reason for
> this warning? Put this in the tag name. Yeah, it makes the name ugly but
> if you ever feel the need to extract/locate/format only a certain kind of
> warning you'll be thankful for that extra information.

Can you provide an example?

> > <note>This builds the C compiler.</note>
> 
> Same goes for "<note>". It's not descriptive enough.
> 
> > <attention>Do not attempt this fix if you don't have Glibc-2.2.3
> > installed.</attention>
> 
> Where's the difference between "<warning>" and "<attention>"? I can only
> repeat: Be more descriptive! Why are you giving a warning? Why does this
> require special attention? Encode that in the tag name.

As an attribute? Or are you suggesting that each warning/note/attention
tag be different, depending on the text of the message? Such as:

<attention_notfor_oldglibc> ?

> > 5. Chapter construction
> > 
> > <chapter id="chapter01" file="chapter01.html" dir="chapter01">
> 
> Avoid abstract ids when you can. Use descriptive names. "chapter01"
> doesn't make much sense as an id. The 1st chapter is characterized by
> being the 1st in the document. XSLT/XPath can count that by itself.

Okay.

> If you plan to put the chapter with id chapter01 as 2nd chapter some
> day in the future, it becomes even worse a name.

True. Chapters were switched a while back, and that was quite a
hassle.

> > <title>Introduction</title>
> > 
> > <sections>
> > &c1-acknowledgements;
> > &c1-how;
> > &c1-conventions;
> > &c1-version;
> > &c1-mirrors;
> > &c1-changelog;
> > &c1-maillists;
> > &c1-newsserver;
> > &c1-faq;
> > &c1-contactinfo;
> > </sections>
> 
> HELP! Entities! Argh! NO!

Would you prefer some sort of link?

-- 
timothy(at)linuxfromscratch.org

-*- "Share and Enjoy" || "Go stick your head in a pig" -*-
-- 
Unsubscribe: send email to listar at linuxfromscratch.org
and put 'unsubscribe lfs-dev' in the subject header of the message



More information about the lfs-dev mailing list