cvs commit: doc/en_US.ISO8859-1/books/porters-handbook book.sgml

[Hiroki Sato]

Rene Ladan <rene at FreeBSD.org> wrote
  in <4B437B44.9060308 at freebsd.org>:

re> On 04-01-2010 22:28, Doug Barton wrote:
re> > Gavin Atkinson wrote:
re> >> On Mon, 4 Jan 2010, Doug Barton wrote:
re> >>> dougb       2010-01-04 20:38:15 UTC
re> >>>
re> >>>    Modified files:
re> >>>      en_US.ISO8859-1/books/porters-handbook book.sgml
re> >>>    Log:
re> >>>    Actually having the $FreeBSD$ tag expanded in the example rc.d script
re> >>>    did not end up looking as cool as I thought it would, so switch to an
re> >>>    unexpanded example.
re> >>>
re> >>>    Fix the text in the new paragraph to work better around the markup.
re> >>
re> >>>        <para>  Unless there is a good reason to start the service
re> >>> 	earlier all ports scripts should use
re> >>> -	<programlisting>REQUIRE: LOGIN</programlisting>. If the service
re> >>> +	<programlisting>REQUIRE: LOGIN</programlisting>  If the service
re> >>> 	runs as a particular user (other than root) this is mandatory.
re> >>
re> >> This is now grammatically incorrect.  I actually think the original is
re> >> better than any rewording I can come up with.
re> >
re> > Take a quick look at the page before it auto-updates. The old way the
re> > period ends up all by itself in the text after the programlisting box,
re> > so it looks like this:
re> >
re> > . If the service
re> >
re> This feels like working around some bug/shortcoming in the markup
re> engine to me (?)  The source text never knows the dimensions and font
re> of the resulting output (computer screen/paper/pda/...).

 I guess the original version was intended to use an inline format,
 not a displayed block.  If it is true, <literal> should be used
 instead of <programlisting> here.  Or if a displayed block was
 preferred, the sentence should be fixed as Gabor suggested.

 DocBook specification claims "processing expectations" for each
 element, not only semantics of the markup.  The structure like
 "<para>This is <programlisting>foo</>.  That is bar.</>" is allowed
 in the spec but should be avoid because it leads to an odd output.

-- Hiroki
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/cvs-doc/attachments/20100105/b5c0f580/attachment.pgp