[Fwd: Some questions to can start my work (long)]

Randy McMurchy randy at linuxfromscratch.org
Sat Apr 16 16:42:21 PDT 2005


-------- Original Message --------
Subject: Some questions to can start my work (long)
Date: Sat, 16 Apr 2005 23:51:24 +0200
From: M.Canales.es <manuel at linuxfromscratch.org>
Reply-To: BLFS Book Maintenance List <blfs-book at linuxfromscratch.org>
Organization: Poder para Tux !!!
To: blfs-book at linuxfromscratch.org

Hi.

I would start my work  with the XML/XSL/CSS code in one or two days, but first
I want to solve some dudes.

Disclaimer: The next are only personal opinions. I will apply the tagging
policies decides by the editorial stuff regardless if that policies matches
my preferences or not.

First, I think that the next Note placed in the Chapter 7. Overall editing
policy from the Editor's Manual is very valid and should be used as a rule:

"Note

There are several ways to use the userinput, command, option, replaceable,
parameter, envar, constant, varname, etc., tags. Don't overdo it. In many
cases, the tags will not change the output and will make editing the XML text
more difficult. Generally, a single set of tags around a block of text is
sufficient."

This is applicable, IMHO, to this two issues:

.- The applications' names tagging: Taking the libIDL.xml file like an
example, the package name isn't tagged in the sect1 title, but is tagged as
<application>lib<acronym>IDL</acronym></application> in all other titles and
in the text blocks. My proposal is to not tag packages' names into any title
and to tag them only as <application> into <para>s (dropping the <acronym>
tag). Also, most packages are named in lowercase in the text, but are named
in uppercase in the Index. That don't look very consistent to me.

.- The command blocks are tagged as <screen><userinput><command>. Yes, that is
semantically very correct, but also very long and redundant. I prefer the
approach used in LFS that, as a plus, allow to have the same look in both
HTML and PDF for files creation commands (the ones with "cat ... EOF")


About the "Introduction to ..." sections: I will want to get rid of all that
<sect3> and <sect4> tags replacing it by <bridgehead> tags. That, together
with all the <sect3> tags dropped from the "Contents" sections with the new
Index tagging, could allow to as to add the sections numberings without a big
cost in rendering time.

About the role="root" attribute: I think that this was added to can have a
different look in that commands (maybe to add a border or to use other
background color). If that is the goal, the attribute must be moved to the
<screen> tag due that is the <screen> tag the one that creates the box area
containing the commands. Having it into <userinput> we can only to change by
default the text font attributes.

About the "Short Descriptions" sections: I suppose that the addition of the
<?dbhtml list-presentation="table"?> processing instruction was accepted, only
delayed until have 6.0 ready, true?. Also, the descriptives texts start in
lowercase and end with a dot. That is just the opposite to how was done in
LFS for publication purposes.

About the use of <parameter>/<option>: I suppose that <parameter> is used only
in the "Command Explanations" section for parameters used in the book's
commands, and <option> for optional parameters and to tag any parameter into
the text flow, is that rigth?

Lastly (for now), I want to add some new inline tags, basically <systemitem
class="...."> for user/group names and filesystems.

[some replies already posted to blfs-book]



More information about the blfs-dev mailing list