[Clfs-dev] Simplification of the XML

[Joe Ciccone]

A long time ago there was a discussion about simplifying the XML. At
this time, I have a more then functional syntax that can be put to use.
Here is a link to the branch:
http://git.cross-lfs.org/?p=cross-lfs.git;a=shortlog;h=refs/heads/simp

Files of interest in branch simp:

  BOOK/schema/clfs/0.1/rng/clfs.rnc (Compat format is easier to read)
  BOOK/final-system/common/bash.xml (First Test Subject)
  BOOK/stylesheets/clfs-profile.xsl (Where the magic happens)

This is a multi-pass rendering process now. When its all done we will
have a single XML tree for all architectures and variants. I'm still
fine-tuning and tweaking the stylesheet. Here are the basics of how it
will work. Anywhere in the entire XML tree the attributes c:arch,
c:multilib are available, and inside of a c:package element c:bits is
available.

What these attributes do, you can think of them like a filter. Just like
DocBook's profiling. c:arch and c:bits are comma (,) separated lists and
c:multilib is a boolean (true,false). So for example:

<para c:multilib="true">will only see this on multilib builds</para>
<para c:arch="x86,x86_64,x86_64-64">will only see this on x86*.</para>

If you've worked with the XML I'm sure you can already see the benefits.
In the past there have been concerns about validating. That is where the
switch we made to the Relax-NG schema comes in. We may have a problem
using an integrated editor with this format. But xmllint can validate
this document against a custom schema that is in the source tree. This I
want to move into a git sub-module so it can be shared with all of the
books.

A general overview of what happens here. Everywhere a sect1 can appear a
c:package element can appear as well. c:package has 2 mandatory
arguments, id and c:multibuild. id speaks for itself. c:multibuild
specifies whether it will be built multiple times on multilib or not.

Inside of the c:package element there are several children. c:title,
c:version, and c:description speak for themselves. They are used to
build the sect2[@role='package'] section. c:install is used to build the
sect2[@role='installation'] section and can contain c:para, c:command,
c:note, and c:warning. c:config, similar to c:install, is used to build
the sect2[@role='configuration'] section and can contain c:para,
c:command, c:note, and c:warning.

These sections are pretty easy to follow. Here's the fun one,
c:contents. This element allows us to easily build out the contents
section of the page, including of automatically populating the
indexterms based on the type of element you nest into it.

c:contents can contain 3 different elements. c:program, c:library, and
c:directory. Each contain a c:name and c:description element that speak
for themselves. This make maintaining the content section of the page
MUCH easier. See BOOK/final-system/common/bash.xml in the simp branch
for an example of putting this all together.

What is not implemented yet but is being worked on.
* a variant element to specify in the index if the package belongs to
cross-tools, the temp system or the final system.
* A wrapper for command explanations (configure/make arguments, etc...)

Please, take a look, evaluate the work that's been done. I'm going to
work on the features not implemented above as well as convert 2 or 3
packages in the final system over. Plus maybe try to simplify the
stylesheet a little bit. Make comments / suggestions for improvement. If
you've made it this far you must be interested. :p

I would love to try and get this integrated within the next few weeks.
Barring no objections. I really want to get some feedback on this too,
as it is such a major change.

Thanks and Happy Easter,

-- 
Joe Ciccone