ALFS DTD Syntax Doc v3.1

James Robertson jwrober at linuxfromscratch.org
Thu Jun 3 15:18:10 PDT 2004


Richard A Downing FBCS wrote:
> Some things I didn't change, but just observe below...
> 
> General observations:
> 
> 1) I think a reference to a good xml primer, such as O'Rielly's 
> 'Learning XML' would enhance XML & DTD Syntax.  Indeed, you could remove 
> it entirely if you found a free one on-line.  I'll do some research.

That would be helpful.  I culled that together from a bunch of stuff on 
the net.

> 2) In all the element descriptions: s/one of the many main operation 
> elements/a main operation element/  The current version sounds like an 
> advert to me.

How about "one of the top-level operation elements" instead.  What I am 
trying to say is that there is a certain set of elements that are a 
child to (alfs), but a parent to just about everything else.

> 3) Sometimes you use the contruction:  'this allows one to...', and 
> sometimes you say: 'this allows you to...'  You should make up your mind 
> and be consistent - I used 'one' in my patches, but I prefer 'you'.  I 
> really hate: 'this allows to...' as, without a pronoun, it isn't English.

Ok, I will fix.  I like "you" as well.

> Stuff I couldn't just fix, due to ignorance:
> 
> Download:  Shouldn't the bash equiv have an md5sum command in it?
> Unpack:  ditto.

Ok, will look into.  More comments in the inline patch....

> Hope this helps.
> 
> (Note, I'm not a patch-wiz, so I may not have done that right - just 
> kick me... I've kept the data)
> 
> R.
> 
> ------------------------------------------------------------------------
> 
> diff -Naur alfs_dtd/elem_configure.xml my_alfs_dtd/elem_configure.xml
> --- alfs_dtd/elem_configure.xml	2004-05-29 03:55:48.000000000 +0000
> +++ my_alfs_dtd/elem_configure.xml	2004-06-03 05:12:46.584377000 +0000
> @@ -72,8 +72,6 @@
>  parameter : </para>
>  
>  <screen><userinput><configure base="/usr/src/mypackage/">
> -	<prefix>CFLAGS="..."<prefix>
> -	<prefix>CXXFLAGS="..."<prefix>
>  	<param>--prefix=/opt/mypackage</param>
>  </configure></userinput></screen>

Why did you pull the two prefix examples here?

> diff -Naur alfs_dtd/elem_destination.xml my_alfs_dtd/elem_destination.xml
> --- alfs_dtd/elem_destination.xml	2004-05-29 03:55:48.000000000 +0000
> +++ my_alfs_dtd/elem_destination.xml	2004-06-03 05:17:17.413354000 +0000
> @@ -22,8 +22,8 @@
>  <title>Description</title>
>  
>  <para>The element <filename>destination</filename> is used to specify the
> -name of the destination file or directory when processing an element it
> -occurs in.</para> 
> +name of the destination file or directory when processing an element
> +in which it occurs.</para> 

Fixed.

>  </sect2>
>  
> diff -Naur alfs_dtd/elem_download.xml my_alfs_dtd/elem_download.xml
> --- alfs_dtd/elem_download.xml	2004-06-03 05:22:47.379327888 +0000
> +++ my_alfs_dtd/elem_download.xml	2004-05-29 03:55:48.000000000 +0000
> @@ -28,8 +28,8 @@
>  
>  <para>The element <filename>download</filename> is one of the many main
>  operation elements. It is used to specify one or several URLs from which a
> -file can be downloaded. Optionally, a digest can be specified to check
> -that the file being downloaded is both the right one and has not been tampered with.</para>
> +file can be downloaded, and optionally a digest to check that the file
> +being downloaded if the right one.</para>
>  
>  <para>The sub-element <filename>file</filename> contains the name of the
>  file to be downloaded.</para>

Fixed.

> diff -Naur alfs_dtd/elem_link.xml my_alfs_dtd/elem_link.xml
> --- alfs_dtd/elem_link.xml	2004-05-29 03:55:48.000000000 +0000
> +++ my_alfs_dtd/elem_link.xml	2004-06-03 05:27:20.366610000 +0000
> @@ -32,7 +32,7 @@
>  operation elements. It allows you to create a hard or symbolic link.</para>
>  
>  <para>The sub-element <filename>target</filename> gives the name(s) of the
> -targets.</para>
> +target.</para>
>  
>  <para>The sub-element <filename>option</filename> provides a means to pass
>  an option to the <command>ln</command> command.</para>

Fixed.

> diff -Naur alfs_dtd/elem_move.xml my_alfs_dtd/elem_move.xml
> --- alfs_dtd/elem_move.xml	2004-05-29 03:55:48.000000000 +0000
> +++ my_alfs_dtd/elem_move.xml	2004-06-03 05:37:19.081228000 +0000
> @@ -42,10 +42,10 @@
>  to the destination, using the specified option if present.</para>
>  
>  <para>The sub-element <filename>source</filename> contains the name of
> -the directory were the source file is.</para>
> +the source file and its directory.</para>
>  
>  <para>The sub-element <filename>destination</filename> contains the name of
> -the destination directory for the <command>mv</command> command.</para>
> +the destination directory (and, optionally, the filename) for the <command>mv</command> command.</para>
>  
>  <para>The attribute <filename>base</filename> gives the name of the
>  directory in which the new directory will be created. See

Fixed.

> diff -Naur alfs_dtd/elem_name.xml my_alfs_dtd/elem_name.xml
> --- alfs_dtd/elem_name.xml	2004-05-29 03:55:48.000000000 +0000
> +++ my_alfs_dtd/elem_name.xml	2004-06-03 05:38:21.579146000 +0000
> @@ -30,7 +30,7 @@
>  <title>Description</title>
>  
>  <para>The element <filename>name</filename> is used to specify a name for
> -some commands that requires it.</para>
> +those commands that require it.</para>
>  
>  </sect2>

Fixed.

> diff -Naur alfs_dtd/elem_option.xml my_alfs_dtd/elem_option.xml
> --- alfs_dtd/elem_option.xml	2004-05-29 03:55:48.000000000 +0000
> +++ my_alfs_dtd/elem_option.xml	2004-06-03 05:39:34.898587000 +0000
> @@ -23,8 +23,8 @@
>  <sect2>
>  <title>Description</title>
>  
> -<para>The element <filename>option</filename> allows to specify an option
> -of the englobing element.</para>
> +<para>The element <filename>option</filename> allows one to specify an option
> +of the enclosing element.</para>
>  
>  </sect2>

Well.  Enclosing is not really that correct, englobing is.  How about 
parent, that is correct to and should be understandable by non-native 
english speakers since XML supports parent/child relationships.

> diff -Naur alfs_dtd/elem_packageinfo.xml my_alfs_dtd/elem_packageinfo.xml
> --- alfs_dtd/elem_packageinfo.xml	2004-05-29 02:45:39.000000000 +0000
> +++ my_alfs_dtd/elem_packageinfo.xml	2004-06-03 05:42:42.089438000 +0000
> @@ -24,7 +24,7 @@
>  <sect2>
>  <title>Description</title>
>  
> -<para>The element <filename>packageinfo</filename> groups elements containg
> +<para>The element <filename>packageinfo</filename> groups elements containing
>  information about the package, namely a description and some dependency
>  relationship(s).</para>

Fixed

> diff -Naur alfs_dtd/elem_param.xml my_alfs_dtd/elem_param.xml
> --- alfs_dtd/elem_param.xml	2004-05-29 04:07:41.000000000 +0000
> +++ my_alfs_dtd/elem_param.xml	2004-06-03 05:43:42.216118000 +0000
> @@ -21,7 +21,7 @@
>  <sect2>
>  <title>Description</title>
>  
> -<para>This element is used to specify a parameter of the englobing
> +<para>This element is used to specify a parameter of the enclosing
>  element.</para>
>  
>  </sect2>

Fixed to "parent".

> diff -Naur alfs_dtd/elem_prefix.xml my_alfs_dtd/elem_prefix.xml
> --- alfs_dtd/elem_prefix.xml	2004-05-29 03:31:01.000000000 +0000
> +++ my_alfs_dtd/elem_prefix.xml	2004-06-03 05:45:23.085706000 +0000
> @@ -22,7 +22,7 @@
>  <title>Description</title>
>  
>  <para>The element <filename>prefix</filename> provides a means to
> -specify an environment variable or some other prefix to the englobing
> +specify an environment variable or some other prefix to the enclosing
>  element.</para>
>  
>  </sect2>

Fixed to "parent".

> diff -Naur alfs_dtd/elem_requires.xml my_alfs_dtd/elem_requires.xml
> --- alfs_dtd/elem_requires.xml	2004-05-29 03:31:39.000000000 +0000
> +++ my_alfs_dtd/elem_requires.xml	2004-06-03 05:48:16.317042000 +0000
> @@ -24,7 +24,7 @@
>  <title>Description</title>
>  
>  <para>The element <filename>requires</filename> denotes a dependency
> -between two packages. The package containg the
> +between two packages. The package containing the
>  <filename>requires</filename> element depends on the package whose name is
>  contained in the <filename>name</filename> sub-element.</para>

Fixed.

> diff -Naur alfs_dtd/elem_root.xml my_alfs_dtd/elem_root.xml
> --- alfs_dtd/elem_root.xml	2004-05-29 04:18:33.000000000 +0000
> +++ my_alfs_dtd/elem_root.xml	2004-06-03 05:49:12.739912000 +0000
> @@ -17,7 +17,7 @@
>  
>  <sect2><title>Description</title>
>  
> -<para>The element <filename>root</filename> allow to specify the name of a
> +<para>The element <filename>root</filename> allows one to specify the name of a
>  directory which will be the root directory for the commands of the
>  stage.</para>

Fixed to "you".

> diff -Naur alfs_dtd/elem_source.xml my_alfs_dtd/elem_source.xml
> --- alfs_dtd/elem_source.xml	2004-05-29 03:32:05.000000000 +0000
> +++ my_alfs_dtd/elem_source.xml	2004-06-03 05:50:16.981270000 +0000
> @@ -19,8 +19,8 @@
>  <sect2>
>  <title>Description</title>
>  
> -<para>The element <filename>source</filename> is used to specify name of
> -the source in the englobing element.</para>
> +<para>The element <filename>source</filename> is used to specify the name of
> +the source in the enclosing element.</para>
>  
>  </sect2>

Fixed to "parent".

> diff -Naur alfs_dtd/elem_textdump.xml my_alfs_dtd/elem_textdump.xml
> --- alfs_dtd/elem_textdump.xml	2004-05-29 04:18:33.000000000 +0000
> +++ my_alfs_dtd/elem_textdump.xml	2004-06-03 05:56:07.206734000 +0000
> @@ -28,7 +28,8 @@
>  <title>Description</title>
>  
>  <para>The element <filename>textdump</filename> is one of the many main
> -operation elements.</para>
> +operation elements. It allows one to create a text file containing
> +specified text.</para>

Fixed with "you".

>  <para>The sub-element <filename>file</filename> contains the name of the
>  file to be created.</para>
> @@ -39,12 +40,12 @@
>  content of this element, one removes the leading blanks up to and including
>  a '=' character.</para>
>  
> -<para>The attribute <filename>base</filename> allows to specify the
> -directory in which the file creation will be perforemd. See
> +<para>The attribute <filename>base</filename> allows one to specify the
> +directory in which the file creation will be performed. See
>  <xref linkend="elem_base"/>.</para>

Fixed to "you".

> -<para>The attribute <filename>mode</filename> allows to specify the append
> -creation mode.</para>
> +<para>The attribute <filename>mode</filename> allows one to specify
> +the creation mode. Only append is currently permitted.</para>

Fixed to "you".

>  </sect2>
>  
> diff -Naur alfs_dtd/elem_unpack.xml my_alfs_dtd/elem_unpack.xml
> --- alfs_dtd/elem_unpack.xml	2004-05-31 18:51:20.000000000 +0000
> +++ my_alfs_dtd/elem_unpack.xml	2004-06-03 05:59:38.470850000 +0000
> @@ -31,15 +31,15 @@
>  directory</para>
>  
>  <para>The sub-element <filename>reference</filename> gives the URL of the
> -archive, which is used if the archive file is not available locally.</para>
> +archive; it is only used if the archive file is not available locally.</para>

Fixed.

>  <para>The sub-element <filename>digest</filename> gives the digest of the
>  archive, as computed by openssl, using the digest type specified in the
>  attribute <filename>type</filename>.</para>
>  
>  <para>The sub-element <filename>archive</filename> gives the name of the
> -archive, and the sub-element <filename>destination</filename> given the
> -name of the directory in which the archive is unpacked</para>
> +archive, and the sub-element <filename>destination</filename> gives the
> +name of the directory in which the archive is unpacked.</para>
>  
>  </sect2>

Fixed.

> diff -Naur alfs_dtd/elem_user.xml my_alfs_dtd/elem_user.xml
> --- alfs_dtd/elem_user.xml	2004-05-29 04:18:33.000000000 +0000
> +++ my_alfs_dtd/elem_user.xml	2004-06-03 06:00:35.423549000 +0000
> @@ -22,7 +22,7 @@
>  <sect2>
>  <title>Description</title>
>  
> -<para>The element <filename>user</filename> allow to specify a user ID that
> +<para>The element <filename>user</filename> allow one to specify a user ID that
>  will be the effective user ID when executing the commands of the stage to
>  which it applies.</para>

Fixed to "you".

> diff -Naur alfs_dtd/elem_utilizes.xml my_alfs_dtd/elem_utilizes.xml
> --- alfs_dtd/elem_utilizes.xml	2004-05-29 04:18:33.000000000 +0000
> +++ my_alfs_dtd/elem_utilizes.xml	2004-06-03 06:03:18.474157000 +0000
> @@ -24,15 +24,15 @@
>  <title>Description</title>
>  
>  <para>The element <filename>utilizes</filename> indicates that the package
> -containg the <filename>utilizes</filename> element utilizes the package
> +containingg the <filename>utilizes</filename> element utilizes the package
-------------^

Heh - another typo!

>  whose name is contained in the <filename>name</filename> sub-element, but
> -does not depend on it, in which case the element
> -<filename>requires</filename> is used.</para>
> +does not depend on it (in which case the element
> +<filename>requires</filename> should be used).</para>

Fixed.

>  <para>The actual name is put into a <filename>name</filename> element
> -because we might want to add a version in a future version. To work
> -properly, then element <filename>name</filename> must be defined in the
> -same profile.</para>
> +because we might want to add a version in a future version.</para>
> +<note>To work properly the element <filename>name</filename> must be
> +defined in the same profile.</note>
>  
>  </sect2>
>  
> 

Fixed.

Thanks Richard.

-- 
James Robertson -- jwrober at linuxfromscratch dot org
Reg. Linux User -- #160424 -- http://counter.li.org
Reg. LFS User   -- #6981   -- http://www.linuxfromscratch.org
LFS Bugzilla Maintainer    -- http://{blfs-}bugs.linuxfromscratch.org



More information about the alfs-discuss mailing list