Thread: Need help with SGML again
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
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!
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...
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
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
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
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
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
> > 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
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
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
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
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
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
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
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
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