Thread: Release.sgml markup

Replace <sectN> with <section>, update older style formatting to match
the newer style, escape all the appropriate places with <![CDATA[ ...
]]> (easier than properly converting characters to escaped format).

All of this was done to make it possible to run some automated
processing on the file. The changes should also make it easier to
process with XSLTs when Peter implements it and come out with a
consistent style.

On Tue, 15 Jul 2003, Rod Taylor wrote:

> Replace <sectN> with <section>,

Why?

> update older style formatting to match
> the newer style, escape all the appropriate places with <![CDATA[ ...
> ]]> (easier than properly converting characters to escaped format).

Better replace all those with real <itemizedlist> elements, because the
current markup is kind of silly and leads to problems when formatting the
plain-text renditions.

> All of this was done to make it possible to run some automated
> processing on the file.

What stops you from automated processing now?

--
Peter Eisentraut   peter_e@gmx.net

On Thu, 2003-07-17 at 08:16, Peter Eisentraut wrote:
> On Tue, 15 Jul 2003, Rod Taylor wrote:
>
> > Replace <sectN> with <section>,
>
> Why?

Actually, primarily so that I can run xinclude on it and get reasonable
results that can be dumped directly within other parts of other
documents at different levels without having to transform it.

sectN style was created due to the limitations of the tools available at
the time -- it was never an overly good idea.

> > update older style formatting to match
> > the newer style, escape all the appropriate places with <![CDATA[ ...
> > ]]> (easier than properly converting characters to escaped format).
>
> Better replace all those with real <itemizedlist> elements, because the
> current markup is kind of silly and leads to problems when formatting the
> plain-text renditions.

I debated doing that but figured I would be better off writing an XSL
transform to do it for me since Bruce will find the file more difficult
to edit.

Anyway, I will send in another copy with everything in itemizedlist
elements.

<listitem>
 <para>
  Release note entry
  (<personname><firstname>Name</firstname></personname>)
 </para>
</listitem>

Would you prefer that the <personname> elements be inside of a
<simplelist type="inline"> when there are several people involved in the
note?

If that was done, the brackets could be applied by the stylsheet based
on all simplelists inside listitems within that appendix ID.

> > All of this was done to make it possible to run some automated
> > processing on the file.
>
> What stops you from automated processing now?

Nothing if the file is consistent.  Basically, what I working with
individual items in the release notes.

- The differences in prefix spacing was making it difficult to find
where an item began or finished.

- The differences in header formatting made it very difficult to grab
titles for content sections.  Some were text inline a programlisting,
others were section/title/text().

- Lack of a space before the (Developer) postfix made it difficult to
separate a name assignment from arbitrary comments attached to the note.

Second try.. GZipped patches were rejected due to size, but BZip'd ones
should get through.

On Sat, 2003-07-19 at 13:42, Rod Taylor wrote:
> Attached is the new file based on itemizedlists blocks, and simplelist
> blocks for the names.
>
> Simplelist was used with the intent that stylesheets would dictate
> surrounding brackets at some point in the future.
>
> - The few email addresses in the file were surrounded with <email> tags
> - Release 6.4 had an area requiring sub-itemizedlists (rule work)
>
> Attached is the 7.3.1 HTML (enough to show impact of changes) and the
> patch itself.
>
> On Thu, 2003-07-17 at 04:16, Peter Eisentraut wrote:
> > On Tue, 15 Jul 2003, Rod Taylor wrote:
> >
> > > Replace <sectN> with <section>,
> >
> > Why?
> >
> > > update older style formatting to match
> > > the newer style, escape all the appropriate places with <![CDATA[ ...
> > > ]]> (easier than properly converting characters to escaped format).
> >
> > Better replace all those with real <itemizedlist> elements, because the
> > current markup is kind of silly and leads to problems when formatting the
> > plain-text renditions.
> >
> > > All of this was done to make it possible to run some automated
> > > processing on the file.
> >
> > What stops you from automated processing now?

Rod Taylor writes:

> Attached is the new file based on itemizedlists blocks, and simplelist
> blocks for the names.
>
> Simplelist was used with the intent that stylesheets would dictate
> surrounding brackets at some point in the future.

I don't understand that.  The names are quite obviously not lists, and I
don't see what stylesheets providing the brackets will gain us, except
breaking the semantics of simplelist.

--
Peter Eisentraut   peter_e@gmx.net

On Mon, 2003-07-21 at 07:50, Peter Eisentraut wrote:
> Rod Taylor writes:
>
> > Attached is the new file based on itemizedlists blocks, and simplelist
> > blocks for the names.
> >
> > Simplelist was used with the intent that stylesheets would dictate
> > surrounding brackets at some point in the future.
>
> I don't understand that.  The names are quite obviously not lists, and I

They are lists. Sometimes of 1 name, sometimes of 2, sometimes several.
(Bob, Joe, Tom)  <- List of 3 names, or am I missing something obvious?

A small set of items with minimal decoration is exactly what Simplelist
is for.  In this specific case, they are inline lists.

As for the brackets.  Currently they are a part of the content in order
to achieve a specific style in the output of the resulting page. The
data could be tabular (items on left, names to right), different type of
bracket, removed entirely for different outputs, or perhaps different
names would be processed in different ways (Bruce could be hyperlinked
to his homepage via the stylesheet for HTML output only) -- thus it is
the job of the stylesheets to manage.

But, if you don't want simplelists, feel free to:

s/<simplelist><member>//
s/</member></simplelist>//
s/</member><member>/, /

Rod Taylor writes:

> As for the brackets.  Currently they are a part of the content in order
> to achieve a specific style in the output of the resulting page. The
> data could be tabular (items on left, names to right), different type of
> bracket, removed entirely for different outputs, or perhaps different
> names would be processed in different ways (Bruce could be hyperlinked
> to his homepage via the stylesheet for HTML output only) -- thus it is
> the job of the stylesheets to manage.

But you are trying to attach additional semantics to predefined elements.
The predefined semantics is "<simplelist> is a list".  Your proposed new
semantic is "<simplelist> withing <itemizedlist> within the PostgreSQL
release notes identifies the contributor of the feature identified in the
parent <listitem>".  If you want to go in that direction, you need to
define new elements.

--
Peter Eisentraut   peter_e@gmx.net

On Tue, 2003-07-22 at 15:35, Peter Eisentraut wrote:
> Rod Taylor writes:
>
> > As for the brackets.  Currently they are a part of the content in order
> > to achieve a specific style in the output of the resulting page. The
> > data could be tabular (items on left, names to right), different type of
> > bracket, removed entirely for different outputs, or perhaps different
> > names would be processed in different ways (Bruce could be hyperlinked
> > to his homepage via the stylesheet for HTML output only) -- thus it is
> > the job of the stylesheets to manage.
>
> But you are trying to attach additional semantics to predefined elements.
> The predefined semantics is "<simplelist> is a list".  Your proposed new
> semantic is "<simplelist> withing <itemizedlist> within the PostgreSQL
> release notes identifies the contributor of the feature identified in the
> parent <listitem>".  If you want to go in that direction, you need to
> define new elements.

I see what you mean now.  You are right that the simplelist should use
the "role" attribute for this purpose, which I will do when the time is
appropriate (after the 4.2 doc upgrade + XSL implementation).

Rod Taylor writes:

> Attached is the new file based on itemizedlists blocks, and simplelist
> blocks for the names.

I tried to apply this patch modulo the reservations I expressed, but it's
impossible to sort out those parts.  Apparently you used some automatic
search and replace, because I find simplelist elements where they don't
belong (anything in parentheses?).  Also, I don't want to start using
<section> in some places if we don't have an overall plan for that move.
Personally, I'm find with sticking to sect1.  Even "DocBook: The
Definitive Guide" uses that in its source.  And I know that it makes work
on the stylesheets much easier.

Do you happen to have intermediate versions of the patch lying around that
contain only the change to itemizedlist?

--
Peter Eisentraut   peter_e@gmx.net

On Tue, 2003-07-22 at 15:42, Peter Eisentraut wrote:
> Rod Taylor writes:
>
> > Attached is the new file based on itemizedlists blocks, and simplelist
> > blocks for the names.
>
> I tried to apply this patch modulo the reservations I expressed, but it's
> impossible to sort out those parts.  Apparently you used some automatic
> search and replace, because I find simplelist elements where they don't
> belong (anything in parentheses?).  Also, I don't want to start using

Unfortunately, yes (last set of brackets). I did a few passes over the
file to reformat prior, checked for unescaped characters, and a few
other simple things.

This is one of the things I meant about making it difficult to process
automagically.  I had corrected the anomolies in earlier releases and
found the ones you were referring to in the 7.3 / 7.4 notes.

> Do you happen to have intermediate versions of the patch lying around that
> contain only the change to itemizedlist?

I don't, nor would it help. 90% of the sections are new with this patch
replacing text headers inside programlistings.

If this is what you want, I will convert the sections to sect1, sect2,
sect3 as is appropriate.

It should be noted that sectN will likely be removed in Docbook 5 (see
ruminations thread in docbook@ lists).  If the XSL stylesheets are
'looking ahead', it is suggested you do not use those tags.

Anyway, please tell me what you decide.