Thread: Need help with SGML again

Need help with SGML again

From
Josh Berkus
Date:
Folks,

I'm augmenting runtime-config as requested.  However, I am finding myself
daunted by all the hand-coding SGML I have to do.  Can someone do some
handholding for me?

Particularly, I'd like to know how to:
cross-link to another item on the same page;
producte a bulleted or numbered list;

Help on IRC would be best if possible

Thanks.

--
-Josh Berkus
 Aglio Database Solutions
 San Francisco


Re: Need help with SGML again

From
Roberto Mello
Date:
On Mon, Oct 13, 2003 at 09:01:45PM -0700, Josh Berkus wrote:
> Folks,
>
> I'm augmenting runtime-config as requested.  However, I am finding myself
> daunted by all the hand-coding SGML I have to do.  Can someone do some
> handholding for me?
>
> Particularly, I'd like to know how to:
> cross-link to another item on the same page;
> producte a bulleted or numbered list;

The OpenACS Docbook Primer should give you what you need:

http://openacs.org/doc/openacs-4-6-3/docbook-primer.html

It is for Docbook XML, which (AFAIK, might be wrong) is a superset of
Docbook SGML, but by looking at ohter examples in the docs you shoul dbe
able to assert that by yourself.

There's also the HOWTO-HOWTO from the Linux Documentation Project
(tldp.org)

-Roberto

--
+----|        Roberto Mello   -    http://www.brasileiro.net/  |------+
+       Computer Science Graduate Student, Utah State University      +
+       USU Free Software & GNU/Linux Club - http://fslc.usu.edu/     +
Quer um Chokito? Então pôe o dedo na tomadita!

Re: Need help with SGML again

From
Jeroen Ruigrok/asmodai
Date:
Hi Josh,

-On [20031014 06:12], Josh Berkus (josh@agliodbs.com) wrote:
>Particularly, I'd like to know how to:
>cross-link to another item on the same page;
>producte a bulleted or numbered list;

SGML or XML can't do that by themselves.  You would need a DTD for that,
such as DocBook.

Within DocBook (www.docbook.org) you would use:

<ulink> for cross-links:

<ulink url="blah.html">Go to blah page</ulink>

and

<itemizedlist> for a list with bullets or dingbats or <orderedlist> for a
list with incremental numbering.

<itemizedlist>
  <listitem>blah</listitem>

  <listitem>fu</listitem>
</itemizedlist>

HTH,

--
Jeroen Ruigrok van der Werven <asmodai(at)wxs.nl> / asmodai / kita no mono
PGP fingerprint: 2D92 980E 45FE 2C28 9DB7  9D88 97E6 839B 2EAC 625B
http://www.tendra.org/   | http://www.in-nomine.org/~asmodai/diary/
Only the wisest and the stupidest of men never change...

Re: Need help with SGML again

From
Josh Berkus
Date:
Roberto, Bruce, etc:

OK, I'm almost done with the edits.  My one problem is the cross-linking.  The
only examples of links I can find in the existing docs link to section
headers.  I need to link to particular paragraphs/terms/listitems.   I can't
figure out from the online stuff how to do this.

--
-Josh Berkus

______AGLIO DATABASE SOLUTIONS___________________________
                                        Josh Berkus
   Complete information technology     josh@agliodbs.com
    and data management solutions     (415) 565-7293
   for law firms, small businesses      fax 621-2533
    and non-profit organizations.     San Francisco


Re: Need help with SGML again

From
Josh Berkus
Date:
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


Re: Need help with SGML again

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

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

Josh Berkus wrote:
> 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
>

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

Re: Need help with SGML again

From
Josh Berkus
Date:
People,

> I see vacuum_mem in "runtime-config-resource-memory".  I assume you just
> 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


Re: Need help with SGML again

From
Peter Eisentraut
Date:
Josh Berkus writes:

> 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.

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   peter_e@gmx.net


Re: Need help with SGML again

From
Rod Taylor
Date:
> > Any thoughts on replacing Docbook with something else, someday?
>
> 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.

Attachment

Re: Need help with SGML again

From
Peter Eisentraut
Date:
Rod Taylor writes:

> 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.

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.)

--
Peter Eisentraut   peter_e@gmx.net


Re: Need help with SGML again

From
Josh Berkus
Date:
Peter,

> 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"?)

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?

> > Any thoughts on replacing Docbook with something else, someday?
>
> 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

Re: Need help with SGML again

From
Tom Lane
Date:
Josh Berkus <josh@agliodbs.com> writes:
> Peter,
>> 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"?)

> 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.

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

Re: Need help with SGML again

From
Rod Taylor
Date:
On Wed, 2003-10-15 at 12:29, Peter Eisentraut wrote:
> Rod Taylor writes:
>
> > 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.
>
> 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.)

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?


Attachment

Re: Need help with SGML again

From
Peter Eisentraut
Date:
Rod Taylor writes:

> 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).

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
> the entire toolchain?

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.

--
Peter Eisentraut   peter_e@gmx.net


Re: Need help with SGML again

From
Peter Eisentraut
Date:
Josh Berkus writes:

> 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.

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?

> 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.

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.

--
Peter Eisentraut   peter_e@gmx.net


Re: Need help with SGML again

From
Rod Taylor
Date:
On Wed, 2003-10-15 at 13:58, Peter Eisentraut wrote:
> Rod Taylor writes:
>
> > 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).
>
> 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,

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).





Attachment

Re: Need help with SGML again

From
"Henry B. Hotz"
Date:
At 9:46 AM -0700 10/15/03, Josh Berkus wrote:
>Peter,
>
>>  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"?)
>
>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.

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.
Henry.B.Hotz@jpl.nasa.gov, or hbhotz@oxy.edu