Subject: Re: Need help with SGML again

From: Josh Berkus <[email-masked]>
Date: Tue, 14 Oct 2003 13:26:08 -0700

Bruce,

> I have Peter on IM.  Here is his reply:

If he can come over to IRC, we can have a 3-way.

> Peter Eisentraut: linking is bad anyway.  tell him not to do it.  if the 
material cannot be presented sequentially, it's too complicated. 
> 151255111: ok

??? Do we want linking or do we want lots of duplicate text?    

What I have currently is:

   <sect2 id="runtime-config-basics">
    <title>Basic Runtime Setup</title>

    <para>
    PostgreSQL's default runtime setup is very conservative, and more 
appropriate to an
    old workstation than a modern server machine.  As such, you will certainly 
want to
    change some of the runtime settings before running PostgreSQL for the 
first time.
    After INITDB, database administrators should change most or all of the 
following settings,
    listed in order of how frequently they need adjustment.
    </para>
    <itemizedlist>
    <listitem>tcpip_socket</listitem>
    <listitem>max_connections</listitem>
    <listitem>shared_buffers</listitem>
    <listitem>sort_mem</listitem>
    <listitem>effective_cache_size</listitem>
    <listitem>random_tuple_cost</listitem>
    <listitem>vacuum_mem</listitem>
    <listitem>max_fsm_pages</listitem>
    <listitem>checkpoint_segments</listitem>
    </itemizedlist>

etc.

It's obvious to me that for this each of the setting names should be linked to 
the listitem below for the individual setting.  My only other choice would be 
to *repeat* the configuration text in the "Basic Setup" section, identical 
with the text below where the settings are defined.  This does *not* seem 
effective to me.

-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 14 Oct 2003 16:31:56 -0400 (EDT)

I see vacuum_mem in "runtime-config-resource-memory".  I assume you just
have to point to that section heading.

---------------------------------------------------------------------------

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: Josh Berkus <[email-masked]>
Date: Tue, 14 Oct 2003 14:01:53 -0700

People,

> have to point to that section heading.

Repeating the discussion on IRC for the benefit of other list members:

Per our previous discussion, I'd wanted to set up the "Basics of Config" as a 
index linking to the various common options, and put the specific "how to 
set" text in each GUC var description.   However, SGML does not permit me to 
do this.   

Instead, I will have to have a more-or-less completely seperate "page" 
(section) describing how to set the most common conf options, which will not 
be included in, or link to, the GUC var definitions themselves.

Any thoughts on replacing Docbook with something else, someday?

-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 15 Oct 2003 09:21:10 +0200 (CEST)

> set" text in each GUC var description.   However, SGML does not permit me to

You should consider the documentation like a book.  That has two
consequences:

1. Linking to anything that is not a formal object (having a title and a
number) does not render well in print.  ("for more information, see
paragraph 3 on page 15"?)

2. Lists of links are going to annoy readers.  Readers want information
here and now, not information about where the information is.

DocBook allows you to link almost anything to almost anything, but doing
that is not always a good idea.

> Any thoughts on replacing Docbook with something else, someday?

I don't see anything better arising.

-- 
Peter Eisentraut   [email-masked]

---

From: Rod Taylor <[email-masked]>
Date: Wed, 15 Oct 2003 09:51:45 -0400

> I don't see anything better arising.

Neither do I, but our particular use of docbook is far from the easiest
to work with.

There are many tools which can give a nicer working environment for
editing docbook based documents, but I've yet to find one which fits in
with the PostgreSQL configuration.

Perhaps you could suggest a toolset which can work with our docs and
hide the syntax from the user and give a 1st approximation of what the
final document would look like (without installing tons of tools -- many
of which are difficult to find in non-unix environments).  This would be
much appreciated.

Recently, I've been using Openoffice for a first cut and Conglomerate to
clean the document up. Of course, that uses a strict XML version and I
normally prefer xincludes to entity based includes.

With xincludes, each document is valid individually, as such can be
rendered individually.  You don't need to process the full book to see
what the 2 new paragraphs in section N.n will look like.  Throw an XML
transform at the top for Internet Explorer and you don't need any tools 
outside the text editor, webbrowser, and diff.

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 15 Oct 2003 18:29:27 +0200 (CEST)

> normally prefer xincludes to entity based includes.

If you can find/propose/develop an XML-based setup that has the same
functionality as our current setup, I wouldn't mind switching.  Some
things that I see as requirements are:

1. Does the HTML output look at least as good as the current output?  (The
default DocBook XSLT stylesheets do not, AFAIR.)

2. Is there a toolchain that can create PDFs, that actually work on our
input files?  (FOP does not, AFAIR; PassiveTeX is a pain to set up.)

3. Is there a (mature) toolchain to create man pages?

4. Is there a quick way to verify the validity of the entire document?

5. How does the speed of the new toolchain compare to the current one?

6. What to do about the parameter entities?

7. How hard is it to set up the toolchain?  (xsltproc is pretty wide
spread and would be acceptable.  Java-based tools such as saxon seem like
trouble.)

---

From: Josh Berkus <[email-masked]>
Date: Wed, 15 Oct 2003 09:46:01 -0700

Peter,

> paragraph 3 on page 15"?)

I see what you mean.   Given that I do 95% of my doc browsing in HTML, this 
seems very redundant to me, though; I think it would be interesting to see 
how many users refer to a paper version of the docs.  We may find it's a tiny 
minority.

I'm also annoyed that I found out that the doc strucutre I wanted to use was 
not permitted only after I typed & marked it, but that's hardly your fault.

The way I see it, lack of linking leaves me with 3 choices:
1) Leave things the way they are, which will force new DBAs to scroll/click 
through runtime.sgml looking for the terms I've defined.

2) Create a seperate page/section giving just the basic settings and move the 
tuning information for the 10 settings I've augmennted to that document, 
making things more convenient for new DBAs but annoying experienced ones who 
need to swtich between the new page and the main GUC listing.

3) Copy the information to *both* places, adding repeated text to 
runtime.sgml, and the possibility of the two versions of each text getting 
out of synch.

I'm leaning toward (2).  Thoughts?

> I don't see anything better arising.

Something I could edit WYSWYG comes to mind, or at least standard enough 
DocBook that I could use OpenOffice.org on it.

I'm serious about this.  Documentation writing, like advocacy, is a great task 
for people who want to contribute to the project but don't have the coding 
skills.  Currently, it's very difficult to involve any of those people in 
adding to the docs becuase they have to learn an arcane markup format first, 
for which there are no good tools on Windows.

If we could move the docs to a format supported by a multi-platform WYSWYG 
editor, I'd bet you dinner that we could get at least 4 more regular 
documentation contributors, if not a dozen.

-- 
Josh Berkus
Aglio Database Solutions
San Francisco

---

From: Tom Lane <[email-masked]>
Date: Wed, 15 Oct 2003 13:22:13 -0400

> how many users refer to a paper version of the docs.  We may find it's a tiny

That was my reaction as well.  While I don't want to make the paper
version unusable, I think that the HTML version is considerably more
important.

The compromise I would propose is to do the cross-linking as Josh
wanted, and to have the links in the HTML version go directly to the
paragraphs describing the variables, but in the paper version have the
links just refer to the containing numbered subsections.  (Dunno how
practical this is to implement, though.)

I don't much care for any of the three alternatives Josh mentions,
although if pressed I would opt for duplicating the info.  That might
be the best answer anyway, since the descriptions appropriate in the
main listing might be too terse for novices; that is, I'm not sure the
duplication would or should be exact.

			regards, tom lane

---

From: Rod Taylor <[email-masked]>
Date: Wed, 15 Oct 2003 13:40:17 -0400

> input files?  (FOP does not, AFAIR; PassiveTeX is a pain to set up.)

You don't need to switch toolkits to use XML input files as the source.
Openjade and friends all support XML with the exception of xincludes
(frankly, they're the best part).

A single XML document can be generated out of several from xincluded
source with a xsltproc which is then fed that into openjade.

As far as the HTML goes, the Gnome & FreeBSD documentation teams have
put some work into making the HTML come out right -- some things come
out much better (media items). Print is still lacking, but stated above
we can still use the old toolchain for that.

Is this something that is worth investigating? I'm happy to do the work,
but my process in submitting documentation changes has been lacking (as
shown by non-acceptance).

What would you like as proof of concept for buy in prior to converting
the entire toolchain?

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 15 Oct 2003 19:58:20 +0200 (CEST)

> (frankly, they're the best part).

But the xincludes part kind of invalidates your point, no?  If we just
switch to XML and keep using OpenJade, then we're not really gaining much,
I think.  I'm not attached to OpenJade or DSSSL.  We're not going to get
around using XSLT eventually.  Just don't equate "it's there" with "it
works well on a 1000 page book".

> What would you like as proof of concept for buy in prior to converting

A complete proposal that contains a motivation (such as, "we should
convert to DocBook XML because it enables us to use xincludes, which is
better than entity-based inclusion because it facilitates editing"), plus
precise answers to the questions I posed (except maybe the "does it look
good" part, which can always be fixed).  AFAIR, the past proposals you had
about architecture advancements always fell short in one point or two or
were lacking the, er, vision or time to push it through completely.
Another thing that has more than once held up any kind of conversion is
that people, including myself, always get these ideas in the middle of
beta.  If you want to start hacking around as soon as 7.5 opens, be my
guest.  But I would like to see a complete plan that gives me a good
feeling that by the start of the next beta, we'll be at least as good as
the previous state.

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 15 Oct 2003 20:20:27 +0200 (CEST)

> how many users refer to a paper version of the docs.  We may find it's a tiny

Even in HTML, I don't think that direct links are a good idea.  If you
click on foo.html#bar, does the browser display a red arrow showing the
user what the setter of the link wanted you to read?  No, it just displays
the page near the anchor, and the user is going to have to scroll and
search anyway.  So if you link to the nearest containing section, I think
it's going to be just as good and doesn't make presumptions about the
output mode mechanics.

> The way I see it, lack of linking leaves me with 3 choices:

I really don't know what you're writing, so I can't give you an answer to
this.

> Something I could edit WYSWYG comes to mind,

There are tools for DocBook that do that.  I've never felt the urge to
find out more about them, but you should be able to find information about
them on the docbook-tools list.

> or at least standard enough DocBook that I could use OpenOffice.org on
> it.

DocBook is a standard and our DocBook follows that standard.  What degree
of standard do you need for your tool?

> for which there are no good tools on Windows.

It's not like we're some elite crowd that shuns WYSIWYG for the fun of it.
Whereever you look, people use DocBook.  FreeBSD, KDE, Gnome, Debian, even
the FSF is slowly migrating from Texinfo to DocBook, and every other
random project I see on the net that has some documentation has quite
obviously produced it using DocBook.  Sun and other commercial entities
use it.  Publishers like O'Reilly accept books written in it.  People,
including myself, produce websites, articles, and presentations with it
and take advantage of the common environment.

WYSIWYG is not a good idea for producing large, quality documentation.
That has been known at least since LaTeX, and the W3C preaches it every
day.  When people do WYSIWYG, they start looking for eye candy and don't
concentrate on producing quality content.  The result of that is the web
today: most of what is written in HTML is completely unmaintainable,
unprocessable by anything except possibly the human eye.

---

From: Rod Taylor <[email-masked]>
Date: Wed, 15 Oct 2003 14:24:39 -0400

> switch to XML and keep using OpenJade, then we're not really gaining much,

You didn't read the rest. We do implement and use xincludes in the
source files for the various interfaces to edit with, webbrowser to to
transforms on, etc.

We simply add an xsltproc step prior to OpenJade processing to create a
single document for OpenJade to deal with, rather than forcing OpenJade
to pull parts of documents in via xincludes or system entities.

This will give us the exact same output as prior, but will enable people
such as Josh to edit the docs without panicking (part of the solution is
a recommended toolkit).

---

From: "Henry B. Hotz" <[email-masked]>
Date: Wed, 15 Oct 2003 15:56:19 -0700

>how many users refer to a paper version of the docs.  We may find it's a tiny

Well, just as a data point I DL/print the docs when I upgrade 
Postgres and keep the book on my shelf for reference.  I may be a bit 
of a curmudgeon, but there isn't a computer display around that's as 
high-quality and portable as a piece of paper.
-- 
The opinions expressed in this message are mine,
not those of Caltech, JPL, NASA, or the US Government.
[email-masked], or [email-masked]