The move to custom XML

Matthias Benkmann matthias at winterdrache.de
Tue May 20 13:21:58 PDT 2003


> 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>

If an id is needed, yes I'd use a tag for it. Now what is <page> supposed
to mean? The XML source should not care about pages.

 
> > > 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?

I was thinking of something like <DEPENDENCY-WARNING>, but something like
<WARNING><DEPENDENCY/>
  Don't forget to install foo before installing bar.
</WARNING>

may be better than putting it in the tag name. That way we could select
"WARNING" to get all warnings and "WARNING[DEPENDENCY]" to get just
dependency-related warnings. It would also allow us to have a warning
belong in several categories at the same time (which btw is another reason
not to use attributes such as type="foo". Attributes can not occur
multiple times). 
It's always hard to decide what to do without knowing what kind of
information you need in the future.

> > > <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?

That depends. Sometimes I use an empty tag such as 

<ACKNOWLEDGEMENTS/>

which just serves as a handle that I can attach the template in the
stylesheet to. Sometimes I would keep something in a separate file an do
something like  <INCLUDE>achknowledgements</INCLUDE>.

What is the above code fragment supposed to mean? Note, that I've never
really looked at the XML version of the LFS book, so things that may have
an obvious meaning to you don't for me.

To me it looks like you are piecing together the Introduction section from
entities. Where are those defined?

And why do you want to do it like that in the first place? I would start
out with a more or less monolithic version of the book. I would have all
text with the exception of the package installation instructions and
things such as mail addresses, links,... in one big file, i.e.


SECTION{ TITLE{ Preface }
  SECTION{ TITLE{Foreword}
     blabla
  }

  SECTION{ TITLE{Who would want to read this book}
     blabla
  }

  ...

  SECTION{ TITLE{Organization}
    SECTION{ TITLE{Part I - Introduction}
      blabla
    }
    SECTION{ TITLE{Part II - Preparing for the build}
      blabla
    }

    ...

  }
}

SECTION{ TITLE{ Part I - Introduction }
  SECTION{ TITLE{ Introduction }
    SECTION{ TITLE{Acknowledgements} }
      ACKNOWLEDGEMENTS{
        THANKSTO{ PERSON{Mark Stone MAIL{mstone}} 
                  for donating the linuxfromscratch.org server.}

        THANKSTO{ COMPANY{VA Linux Systems} for providing rack space 
                  and bandwidth for the linuxfromscratch.org server.}

        THANKSTO{ PERSON{Fredrik Danerklint} 
                  for running the se.linuxfromscratch.org mirror.}

        ...        
  
      }
    }
    SECTION{ TITLE{ How things are going to be done}
      blabla
    }

    ...

  }
  
   ...

}

and so forth.

For the package building instructions I would create an extra XML file for
each package named after the package that looks like this

PACKAGE{ 
  NAME{sed}
  VERSIOn{4.0.5}
  PACKAGE-SIZE{488KB}
  ARCHIVE{NAME{}-VERSION{}.tar.bz2}
  PACKAGE-URL{ftp://ftp.gnu.org/gnu/sed/}
  STATIC-SIZE{2MB}
  STATIC-SBU{0.09}
  DYNAMIC-SIZE{2MB}
  DYNAMIC-SBU{0.09}

  CONTENTS{
    CHECKED-AGAINST{3.02}
    PROG{ NAME{sed}
      sed is a stream editor. A stream editor is used to perform basic
      text transformations on an input stream (a file or input from a
      pipeline).
    }
  }

  DEPENDENCIES{
    CHECKED-AGAINST{3.02}
    aclocal, automake, sh, ar, as, ld, ranlib, cmp, chmod, install, ls,
    mv, rm, cc1, collect2, cpp0, gcc, getconf, egrep, fgrep, grep, m4,
    make, gawk, sed, echo, expr, hostname, sleep, install-info, makeinfo,
    cat, tr
  }

  CHAPTER5{
    INSTRUCTION{
      INTRO{ p{ Prepare Sed to be compiled: } } 

      COMMANDS{CPPFLAGS=-Dre_max_failures=re_max_failures2 CONT{} 
                   LDFLAGS="-static" ./configure --prefix=$LFS/static
                   --disable-nls
    }

    INSTRUCTION{
      INTRO{ p{ Continue with installing the package: } }

      COMMANDS{make}
    }

    INSTRUCTION{
      INTRO{ p{ And finish off installing the package: } }

      COMMANDS{ make install }
    }
  }

  CHAPTER6{
    INSTRUCTION{
      INTRO{ p{ Prepare Sed to be compiled: } } 

      COMMANDS{./configure --prefix=/usr --bindir=/bin}
    }

    INSTRUCTION{
      INTRO{ p{ Continue with installing the package: } }

      COMMANDS{make}
    }

    INSTRUCTION{
      INTRO{ p{ And finish off installing the package: } }

      COMMANDS{ make install }
    }

  }
}


About the chapter 6 text being mostly identical to chapter 5. I would keep
that redundancy. I thought about using ids in the chapter 5 instructions
and backreferencing them in the chapter 6 part. I also thought about
declaring common text fragments before the 2 sections and reference them.
I don't like it. It makes it harder to read and write. Considering that
the 2 texts are so close to each other in the same file, there's no
maintenance argument to be made for avoiding the redundancy. Keeping them
in sync with manual copy'n'paste in an editor is so trivial and quick. I
think any kind of mechanism to avoid the redunancy would just introduce
complexity and make things harder to read without being any real help.

Back to the main file of the book:

SECTION{ TITLE{Part III - Building the LFS system}
  SECTION{ TITLE{Installing basic system software}
    SECTION{ TITLE{ Introduction }
      blabla
    }
    SECTION{ TITLE{ About debugging symbols }
      blabla
    }
    SECTION{ TITLE{ Entering the chroot environment }
       p{It is time to enter the KEYWORD{chroot} environment in order 
         to begin installing the packages we need. 
         Before you can chroot, however, you need to 
         become USER{root}, since only root can execute the 
         CMDNAME{chroot} command.
       }

       INSTRUCTION{
         INTRO{ p{ Become root and run the following command to enter the
                   chroot environment:}
         }

         COMMANDS{
           chroot $LFS /static/bin/env -i CONT{}
           HOME=/root TERM=$TERM PS1='\u:\w\$ ' CONT{}
           PATH=/bin:/usr/bin:/sbin:/usr/sbin:/static/bin CONT{}
          /static/bin/bash --login
         }

         EXPLANATION{         
          p{ The CMDFRAGMENT{-i} option given to the CMDNAME{env} command
            will clear all variables
            of the chroot environment. After that, only the ENVVAR{HOME},
            ENVVAR{TERM}, ENVVAR{PS1} and ENVVAR{PATH} variables are set
            again. The CMDFRAGMENT{TERM=$TERM} construct will set the
            ENVVAR{TERM} variable inside chroot to the same value as
            outside chroot; this variable is needed for programs like 
            PROGNAME{vim} and PROGNAME{less} to operate properly. If you
            need other variables present, such as ENVVAR{CFLAGS} or
            ENVVAR{CXXFLAGS}, this is a good place to set them again.
           }
         }
       }

       blabla

    }

    ...

    SECTION{ TITLE{ Creating directories }
     
      blabla

      FHS-COMPLIANCE-NOTE{
        blabla
      }

    }

    SECTION{ TITLE{ Mounting the proc filesystem }

      blabla

      p{ You might get warning messages from the mount command, such as
         these: 
      }

      COMMAND-OUTPUT{
        LINE{warning: can't open /etc/fstab: No such file or directory}
        LINE{not enough memory}
        EXPLANATION{
          p{ Ignore these, they're just due to the fact that the
             system isn't installed completely yet and some files 
             are missing. The mount itself will be successful and 
              that's all we care about at this point.
          }

          p{ The last error (not enough memory) doesn't always show up. 
             It depends on your system configuration (such as the host
              system's Glibc version that was used to compile the mount
               program with). 
          }
        }
      }

    }
 
    ...
    ...
    BUILD{textutils}
    BUILD{sed}
    BUILD{flex}
    ...


  }

}



MSB

-- 
Ambition is a poor excuse for not having enough sense to be lazy.

-- 
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