Date: Wed, 15 Mar 2000 19:09:04 +0200 From: Sheldon Hearn <sheldonh@uunet.co.za> To: doc@FreeBSD.org Subject: Proposal re SGML style Message-ID: <56968.953140144@axl.ops.uunet.co.za>
next in thread | raw e-mail | index | archive | help
Hi folks,
I'd like to propose that we apply to our SGML similar guidelines to the
ones we use for our mdoc style.
This message is long. Please don't read it now if you don't have time
to think about what I'm saying before shooting me down. :-)
I'm busy reviewing Alexey Zelkin's recent IPv6 addition to the Internals
section of the Handbook (just shy of a 2000 line diff). It's a
nightmare (reviewing, not the change). The problem is that, with
wrapped paragraphs (like the one you're reading), diffs take more work
to produce and more work to read.
Consider the status quo:
===
<sect2 id="boot-overview">
<title>Overview of the boot process</title>
<para>FreeBSD uses a three-stage bootstrap by default, which
basically entails three programs which basically call each
other in order (the two <link linkend="boot-blocks">boot
blocks</link>, and the <link
linkend="boot-loader">loader</link>), and which build on the
previous programs understanding and provide increasing amounts
of sophistication.</para>
<para>The kernel is then started, during which devices are
probed for and initialized for use. Once the kernel boot
process is finished, it passes control to the user process
init, which then makes sure the disks are in a usable state,
and then starts the user-level resource configuration which
then mounts filesystems, sets up network cards to act on the
network, and generally starts all the processes that usually
are run on a FreeBSD system at startup.</para>
</sect2>
===
Let's say I'd like to fix this up a little. I either need to create two
different diffs (one for my fixes and another to fix the line wrapping
that fixes necessitate) or I can make one diff. Either way is a pain in
the ass, but observe the diff I get if I choose the latter option:
===
--- status_quo.orig Wed Mar 15 17:46:40 2000
+++ status_quo Wed Mar 15 18:10:05 2000
@@ -2,19 +2,20 @@
<title>Overview of the boot process</title>
<para>FreeBSD uses a three-stage bootstrap by default, which
- basically entails three programs which basically call each
+ basically entails three programs which call each
other in order (the two <link linkend="boot-blocks">boot
blocks</link>, and the <link
- linkend="boot-loader">loader</link>), and which build on the
- previous programs understanding and provide increasing amounts
- of sophistication.</para>
+ linkend="boot-loader">loader</link>). Each of these three
+ builds on the previous program's understanding and provide
+ increasing amounts of sophistication.</para>
- <para>The kernel is then started, during which devices are
+ <para>The kernel is then started, at which time devices are
probed for and initialized for use. Once the kernel boot
- process is finished, it passes control to the user process
- init, which then makes sure the disks are in a usable state,
- and then starts the user-level resource configuration which
- then mounts filesystems, sets up network cards to act on the
- network, and generally starts all the processes that usually
- are run on a FreeBSD system at startup.</para>
+ process is finished, the kernel passes control to the user
+ process &man.init.8;, which then makes sure that the disks
+ are in a usable state. &man.init.8; then starts the user-level
+ resource configuration which mounts filesystems, sets up network
+ cards to act on the network, and generally starts all the
+ processes that usually are run on a FreeBSD system at startup.
+ </para>
</sect2>
====
Put aside the fact that realigning the paragraphs is a pain in the arse
with vi, because there are editors that would do this for me on the fly.
The point here is how difficult it is to read the diff. You find
yourself needing to use your fingers. :-)
Now consider what would happen if we formatted our SGML more like we do
our mdoc. This proposal does not involve removing the use of
indentation, since the two people I brought that up in front of both had
an absolute cow over it.
1) Each new sentence begins flush against the indented left margin.
2) Where a sentence is too long to fit onto an XX-column line (where XX
seems to be 80 in the status quo), it is broken on sentence
fragments (clauses). That means on non-terminal punctiation (parens,
commas, colons, semi-colons, maybe others), prepositions etc.
3) Block tags do not share a line with the text they wrap.
So, if the SGML source adhered to this guideline, we'd have:
===
<sect2 id="boot-overview">
<title>Overview of the boot process</title>
<para>
FreeBSD uses a three-stage bootstrap by default,
which basically entails three programs
which basically call each other in order
(the two
<link linkend="boot-blocks">boot blocks</link>,
and the
<link linkend="boot-loader">loader</link>),
and which build on the previous programs understanding
and provide increasing amounts of sophistication.
</para>
<para>
The kernel is then started,
during which devices are probed for
and initialized for use.
Once the kernel boot process is finished,
it passes control to the user process init,
which then makes sure the disks are in a usable state,
and then starts the user-level resource configuration
which then mounts filesystems,
sets up network cards to act on the network,
and generally starts all the processes
that usually are run on a FreeBSD system at startup.
</para>
</sect2>
===
Now, my single diff looks like this:
===
--- proposed.orig Wed Mar 15 18:34:32 2000
+++ proposed Wed Mar 15 18:34:50 2000
@@ -3,24 +3,26 @@
<para>
FreeBSD uses a three-stage bootstrap by default,
which basically entails three programs
- which basically call each other in order
+ which call each other in order
(the two
<link linkend="boot-blocks">boot blocks</link>,
and the
- <link linkend="boot-loader">loader</link>),
- and which build on the previous programs understanding
- and provide increasing amounts of sophistication.
+ <link linkend="boot-loader">loader</link>).
+ Each of these three builds on the previous program's understanding
+ and provides increasing amounts of sophistication.
</para>
<para>
The kernel is then started,
- during which devices are probed for
+ at which time devices are probed for
and initialized for use.
Once the kernel boot process is finished,
- it passes control to the user process init,
- which then makes sure the disks are in a usable state,
- and then starts the user-level resource configuration
- which then mounts filesystems,
+ the kernel passes control to the user process
+ &man.init.8;,
+ which then makes sure that the disks are in a usable state.
+ &man.init.8;
+ then starts the user-level resource configuration
+ which mounts filesystems,
sets up network cards to act on the network,
and generally starts all the processes
that usually are run on a FreeBSD system at startup.
===
Firstly, notice that I no longer need to use two diffs (one for fixes,
the other for tifying up line wrapping). Also, note that it's much
easier to read the diff without using your fingers on the screen to keep
track of the before and after.
For the moment, forget about how much work would be involved in moving
the docs over to the proposed style (because I'd do that work myself).
Also ignore the fact that this move would create a cvs revision across
which translators would have to hop when merging changes from the
English documents.
Right now, what I'd like to hear is constructive criticism of the
proposed style. What would the drawbacks be? How would this break the
various kinds of output we can generate from the SGML source?
Ciao,
Sheldon.
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?56968.953140144>