Thread: The "Current Release Docs"
The "Current Release Docs" on the PostgreSQL website still look 7.0.Xish.. Just an FYI... -Mitch
On Sun, Apr 15, 2001 at 01:11:34PM -0400, Mitch Vincent wrote: > The "Current Release Docs" on the PostgreSQL website still look 7.0.Xish.. I can't finh the 7.1 PS docs anywhere. The stuff in the doc directory on the FTP sites is from last year, and the docs in the tar files are all SGML and HTML. I could really use a printable copy, but last time I tried to generate it from the SGML, it was a nightmare (and afterward, I discovered that the release docs are apparently made by hand anyway). Am I missing something? -- Christopher Masto Senior Network Monkey NetMonger Communications chris@netmonger.net info@netmonger.net http://www.netmonger.net Free yourself, free your machine, free the daemon -- http://www.freebsd.org/
They're not ready yet. Vince. On Mon, 16 Apr 2001, Christopher Masto wrote: > On Sun, Apr 15, 2001 at 01:11:34PM -0400, Mitch Vincent wrote: > > The "Current Release Docs" on the PostgreSQL website still look 7.0.Xish.. > > I can't finh the 7.1 PS docs anywhere. The stuff in the doc directory > on the FTP sites is from last year, and the docs in the tar files > are all SGML and HTML. I could really use a printable copy, but > last time I tried to generate it from the SGML, it was a nightmare > (and afterward, I discovered that the release docs are apparently > made by hand anyway). > > Am I missing something? > -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 56K Nationwide Dialup from $16.00/mo atPop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
> They're not ready yet.
Since they were deemed non-essential for this release, and since the
release schedule is not built around their creation, I no longer feel
obligated to have them finished on the release date. A nice change from
the deadlines I've been working on for the last three years or so :)
This is the first release with the "no hardcopy" policy, and user
feedback is certainly desirable and appreciated.
I hope to be able to find time to finish them soon; a couple are
essentially done already, but the Reference Manual will be problematic
as usual (the jade RTF output is not handled by M$Word, and exhibits the
same symptoms as when read by Applixware).
- Thomas
I know this isn't really hackers traffic, but... one of the servers in www.postgresql.org is http://postgresql.bbksys.com/ which is giving me 404 errors.. I've mailed webmaster@, but thought this should be mailed on anyway.. - brandon b. palmer, bpalmer@crimelabs.net pgp: www.crimelabs.net/bpalmer.pgp5
On Tue, Apr 17, 2001 at 12:07:26AM +0000, Thomas Lockhart wrote: > > They're not ready yet. > > Since they were deemed non-essential for this release, and since the > release schedule is not built around their creation, I no longer feel > obligated to have them finished on the release date. A nice change from > the deadlines I've been working on for the last three years or so :) > > This is the first release with the "no hardcopy" policy, and user > feedback is certainly desirable and appreciated. My feedback at this time is mostly the desire to know a bit better what prevents the hardcopy docs from being built automatically. I am currently having some trouble compiling jadetex, so I can't take a look at the generated PDF yet, but I assume there's something wrong with it. That seems like a big deficiency in the doc tools, which suprises me, given that they're rather large projects that have been used by other large projects for quite a while. My interest is partly to be able to compile the docs on my own, and partly research - I'm involved in the development of an application that has some hefty documentation requirements, and I was hoping that SGML + free software would come to the rescue. If it's just a matter of time and effort, this may be an big enough area of overlap with work that I can spend Official Time and/or Official Money on it. -- Christopher Masto Senior Network Monkey NetMonger Communications chris@netmonger.net info@netmonger.net http://www.netmonger.net Free yourself, free your machine, free the daemon -- http://www.freebsd.org/
Removed from active rotation and site admin notified. Vince. On Mon, 16 Apr 2001, bpalmer wrote: > I know this isn't really hackers traffic, but... > > one of the servers in www.postgresql.org is > > http://postgresql.bbksys.com/ > > which is giving me 404 errors.. > > I've mailed webmaster@, but thought this should be mailed on anyway.. > > - brandon > > b. palmer, bpalmer@crimelabs.net > pgp: www.crimelabs.net/bpalmer.pgp5 > > > > ---------------------------(end of broadcast)--------------------------- > TIP 2: you can get off all lists at once with the unregister command > (send "unregister YourEmailAddressHere" to majordomo@postgresql.org) > -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 56K Nationwide Dialup from $16.00/mo atPop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
> My feedback at this time is mostly the desire to know a bit better
> what prevents the hardcopy docs from being built automatically. I am
> currently having some trouble compiling jadetex, so I can't take a
> look at the generated PDF yet, but I assume there's something wrong
> with it. That seems like a big deficiency in the doc tools, which
> suprises me, given that they're rather large projects that have been
> used by other large projects for quite a while.
Hmm. Actually, afaik we were the first large open source project to
successfully use the jade toolset for docs. Others have used our project
as an example to help get them going, since as you have already found
out getting the tool chain completely set up is not trivial.
There are at least a few reasons why automatically generating hardcopy
without a final adjustment step is not currently feasible:
1) Table column alignment is not ideal. Many tables are generated with
same-width columns and some end up with large indents on each column.
They just don't fit on the page without adjustments. That is for RTF;
table support in jadetex has always been problematic.
2) Reference pages have a problem. It has *always* been the case that
our reference pages do not format correctly. afaict it is is a problem
with jade->RTF (since the problem shows up in both Applixware and
M$Word) but I do not have much insight into RTF conventions so have not
tracked it down. Very time-consuming hand-editing is required :(
3) Page breaks are not always ideal. Some hand adjustments are desirable
to get a better flow to the docs, especially wrt examples and lists; you
don't want them breaking between pages if you can avoid it, especially
with short examples.
4) Table of contents page numbers are not correct in the RTF output, so
a new ToC must be generated in Applixware or Word.
> My interest is partly to be able to compile the docs on my own, and
> partly research - I'm involved in the development of an application
> that has some hefty documentation requirements, and I was hoping that
> SGML + free software would come to the rescue. If it's just a matter
> of time and effort, this may be an big enough area of overlap with
> work that I can spend Official Time and/or Official Money on it.
SGML+freeSW will do what you need. You can generate hardcopy
automatically, but I'm not sure it is realistic to expect a toolset to
do this for a complicated document without *any* hand adjustments. The
time-saving leverage is still tremendous though, and using these tools
is a net win imho.
Good luck!
- Thomas
Thomas Lockhart <lockhart@alumni.caltech.edu> writes:
> 3) Page breaks are not always ideal. Some hand adjustments are desirable
> to get a better flow to the docs, especially wrt examples and lists; you
> don't want them breaking between pages if you can avoid it, especially
> with short examples.
This objection, at least, could be eliminated if the standard hardcopy
path were through TeX (which I assume is what jadetex does). TeX
understands just fine about discouraging or completely preventing page
breaks within certain groups of lines. In general, TeX is a lot better
suited for book-quality typesetting than any other open-source tool I've
heard of.
It seems to me that all of the other problems you enumerate are simply
bugs in the doc toolchain. We've worked around them rather than tried
to fix them because that was the shortest path to a result, but if Chris
wants to tackle actually fixing them, that would sure be nice. Based on
your comments here, my recommendation would be to forget RTF entirely;
instead, work on getting out the kinks in the TeX pathway.
regards, tom lane
Tom Lane writes: > It seems to me that all of the other problems you enumerate are simply > bugs in the doc toolchain. We've worked around them rather than tried > to fix them because that was the shortest path to a result, but if Chris > wants to tackle actually fixing them, that would sure be nice. Based on > your comments here, my recommendation would be to forget RTF entirely; > instead, work on getting out the kinks in the TeX pathway. The consensus of the authors and others that know what they're saying is essentially that jadetex can't be fixed without a complete rewrite of the Jade TeX backend (jadetex != Jade TeX backend). And currently there's little to no interest or manpower for sweeping changes in Jade. The presently most future-proof free software way to use TeX for formatting DocBook is PassiveTeX, which works through XML and XSL FO. I've tried it once and if I'm not mistaken I got a readable PDF file part of the time. If anyone's interested in helping with the tool chain, look there first. -- Peter Eisentraut peter_e@gmx.net http://funkturm.homeip.net/~peter
> It seems to me that all of the other problems you enumerate are simply
> bugs in the doc toolchain. We've worked around them rather than tried
> to fix them because that was the shortest path to a result, but if Chris
> wants to tackle actually fixing them, that would sure be nice. Based on
> your comments here, my recommendation would be to forget RTF entirely;
> instead, work on getting out the kinks in the TeX pathway.
That is at odds with the current thinking of the jade/dsssl community
(which uses both TeX and RTF), but if someone wants to try it would not
hurt I suppose.
The problem with TeX output is that it is *not* adjustable after the
fact, and that the jade support for things like tables is not adequate
for a real-world document. The jadetex author had concluded that really
fixing it was too much work. Many of the original development community
has moved on to XML tools development, but afaik none are ready for use.
One might want to research the current state of the tools as a starting
point for improvements. At the moment, I'd love someone to dive in to
the RTF reference page problem; I can send samples on request :)
- Thomas
> Hmm. Actually, afaik we were the first large open source project to
> successfully use the jade toolset for docs. Others have used our project
> as an example to help get them going, since as you have already found
> out getting the tool chain completely set up is not trivial.
>
> There are at least a few reasons why automatically generating hardcopy
> without a final adjustment step is not currently feasible:
>
> 1) Table column alignment is not ideal. Many tables are generated with
> same-width columns and some end up with large indents on each column.
> They just don't fit on the page without adjustments. That is for RTF;
> table support in jadetex has always been problematic.
>
> 2) Reference pages have a problem. It has *always* been the case that
> our reference pages do not format correctly. afaict it is is a problem
> with jade->RTF (since the problem shows up in both Applixware and
> M$Word) but I do not have much insight into RTF conventions so have not
> tracked it down. Very time-consuming hand-editing is required :(
>
> 3) Page breaks are not always ideal. Some hand adjustments are desirable
> to get a better flow to the docs, especially wrt examples and lists; you
> don't want them breaking between pages if you can avoid it, especially
> with short examples.
>
> 4) Table of contents page numbers are not correct in the RTF output, so
> a new ToC must be generated in Applixware or Word.
Can I add one more issue:
5) We have been working for translating docs into Japanese using EUC_JP encoding. Converting to HTML is no problem,
butwe cannot get correct results for sgml-> RTF conversion at all. The translated docs are just not be able to read,
showingrandom characters. It seems that openjade supports multibyte encodings at least according to their manuals,
butI can not get it working. I have asked to dssslist but I have not gotten usefull helps yet.
A qustion comes to my mind: Is really sgml is an appropriate doc format for us? For me, LaTeX seems more handy. It
cangenerate HTML using latex2html, and of course can produce beautiful hard copies AUTOMATICALLY for English and
otherlanguages including Japanese.
BTW, I see some odd results from the 7.1 HTML docs. For example, in
parser-stage.html,
"Figure \ref{parsetree} shows the parse tree..."
What is the "\ref{parsetree}"?
--
Tatsuo Ishii
> 5) We have been working for translating docs into Japanese using
> EUC_JP encoding. Converting to HTML is no problem, but we cannot
> get correct results for sgml-> RTF conversion at all. The
> translated docs are just not be able to read, showing random
> characters. It seems that openjade supports multibyte encodings at
> least according to their manuals, but I can not get it working. I
> have asked to dssslist but I have not gotten usefull helps yet.
Sorry you are seeing trouble. I missed seeing your traffic on the dsssl
list to which I am subscribed; which one are you using?
> A qustion comes to my mind: Is really sgml is an appropriate doc
> format for us? For me, LaTeX seems more handy. It can generate HTML
> using latex2html, and of course can produce beautiful hard copies
> AUTOMATICALLY for English and other languages including Japanese.
There is a difference between using techniques which markup content
(DocBook, XML, etc) as opposed to those which markup appearence (latex).
The "wave of the future" is content markup, for a variety of reasons,
unless of course the pundits are sadly mistaken and reaching beyond
their grasp. Which is a possibility ;)
I'll submit that the time I take tweaking output for hardcopy is no more
time that would be spent tweaking latex to get optimal appearance.
> BTW, I see some odd results from the 7.1 HTML docs. For example, in
> parser-stage.html,
> "Figure \ref{parsetree} shows the parse tree..."
> What is the "\ref{parsetree}"?
Looks sort of like latex, eh? :)
They are residual markup for graphics from Stephan's Master's Thesis
which were never transcribed from the originals (gifs?) to a usable
format.
Through disk crashes, system upgrades, and a failed backup device I
*may* no longer have his original tarball. Does anyone else?
- Thomas
Thomas Lockhart <lockhart@alumni.caltech.edu> writes:
> There is a difference between using techniques which markup content
> (DocBook, XML, etc) as opposed to those which markup appearence (latex).
Perhaps I'm stuck in the eighties when I did my thesis in LaTeX, but
I was of the impression that what's considered good style in LaTeX *is*
content-based markup. Sure, a LaTeXer may occasionally be forced to
throw in low-level stuff like a \pagebreak to get nice looking results
... but I fail to understand how this is different from the
output-oriented tweaking you do to the current Postgres docs.
> I'll submit that the time I take tweaking output for hardcopy is no more
> time that would be spent tweaking latex to get optimal appearance.
Except that the LaTeXer does it once. You have to do it over again from
scratch, very laboriously, every time you want to generate good output.
This is a step forward?
Bottom line: I see very little reason to believe that SGML + available
tools represents any real technical advance over TeX + its available
tools. In fact, if one wants decent-looking output it seems to be a
substantial regression. Perhaps it's only that TeX has more than a
ten-year lead in being developed into a usable tool, but from what I can
see from here, the SGML tools we are using are incredibly inferior to
what's been available for a long time for TeX.
regards, tom lane
> Perhaps I'm stuck in the eighties when I did my thesis in LaTeX, but
> I was of the impression that what's considered good style in LaTeX *is*
> content-based markup. Sure, a LaTeXer may occasionally be forced to
> throw in low-level stuff like a \pagebreak to get nice looking results
> ... but I fail to understand how this is different from the
> output-oriented tweaking you do to the current Postgres docs.
That particular operation is the same, and done for the same reasons.
> > I'll submit that the time I take tweaking output for hardcopy is no more
> > time that would be spent tweaking latex to get optimal appearance.
>
> Except that the LaTeXer does it once. You have to do it over again from
> scratch, very laboriously, every time you want to generate good output.
> This is a step forward?
Not true. If you embed pagebreak commands *in the source* then those
breaks *must* be reevaluated every time the docs change. If content is
added or removed, the appropriate place for a page break will likely
change, so things must be tweaked again. From source, not from something
close to final form.
> Bottom line: I see very little reason to believe that SGML + available
> tools represents any real technical advance over TeX + its available
> tools. In fact, if one wants decent-looking output it seems to be a
> substantial regression. Perhaps it's only that TeX has more than a
> ten-year lead in being developed into a usable tool, but from what I can
> see from here, the SGML tools we are using are incredibly inferior to
> what's been available for a long time for TeX.
No argument that TeX is a wonderful tool. But it is trading one set of
problems for another, not fixing every criticism you have.
At the moment, my life will be easier without having to argue religion,
so I can get back to preparing docs ;)
- Thomas
Thomas Lockhart <lockhart@alumni.caltech.edu> writes:
>> This is a step forward?
> Not true. If you embed pagebreak commands *in the source* then those
> breaks *must* be reevaluated every time the docs change. If content is
> added or removed, the appropriate place for a page break will likely
> change, so things must be tweaked again.
Of course, but my point is that you don't have to revisit such decisions
in areas of the docs that haven't changed since last time. The
importance of this depends on the stability of the docs, naturally...
> No argument that TeX is a wonderful tool. But it is trading one set of
> problems for another, not fixing every criticism you have.
Agreed --- but the toolchain we are currently using seems to have
considerably more than its fair share of problems.
> At the moment, my life will be easier without having to argue religion,
> so I can get back to preparing docs ;)
Certainly we aren't going to change toolchains at this point in the 7.1
cycle. I'm just opining that it would make sense to take another look
at an SGML-to-TeX-based process in the future --- especially if we have
someone who is willing to put active effort into improving the docs
toolchain.
regards, tom lane
> 5) We have been working for translating docs into Japanese using
> EUC_JP encoding. Converting to HTML is no problem, but we cannot
> get correct results for sgml-> RTF conversion at all. The
> translated docs are just not be able to read, showing random
> characters. It seems that openjade supports multibyte encodings at
> least according to their manuals, but I can not get it working. I
> have asked to dssslist but I have not gotten usefull helps yet.
>
> A qustion comes to my mind: Is really sgml is an appropriate doc
> format for us? For me, LaTeX seems more handy. It can generate HTML
> using latex2html, and of course can produce beautiful hard copies
> AUTOMATICALLY for English and other languages including Japanese.
Tatsuo, when I added SGML reference pages to the back of my book, I took
the HTML-generated output from SGML and loaded that into LaTeX. I did
have to do a few things:
convert SGML to HTMLhtml2latexadd * to \subsection* ?remove \newlineremove \backslashremove \begin_inset Figure { ? }
to?remove trailing space from Descriptionno table conversionchange $$ to $ $no SQL query conversion, all on one line ,
programlisting and synopsisspace-period and space-comma
It actually was pretty quick. The fixes were more cleaning up strange
conversion from HTML to LaTeX.
As far as I can see, SGML gives us rich content tags, so we can do
things like pull the SGML ref manual pages headings right into pgsql's
help system. However, what it doesn't give you is much control over
appearance except how to map the tags to appearance. You can't tweek
appearance in SGML unless you make special tags for certain appearances.
-- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610)
853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill,
Pennsylvania19026
Bruce Momjian writes: > However, what it doesn't give you is much control over > appearance except how to map the tags to appearance. You can't tweek > appearance in SGML unless you make special tags for certain appearances. How do you derive this conclusion? SGML gives you a boatload of ways to tweak appearance through style sheets. No need to make new tags either (although it sometimes doesn't hurt). -- Peter Eisentraut peter_e@gmx.net http://funkturm.homeip.net/~peter
> Bruce Momjian writes: > > > However, what it doesn't give you is much control over > > appearance except how to map the tags to appearance. You can't tweek > > appearance in SGML unless you make special tags for certain appearances. > > How do you derive this conclusion? SGML gives you a boatload of ways to > tweak appearance through style sheets. No need to make new tags either > (although it sometimes doesn't hurt). You can control the appearance of tags, but can you make certain tags appear differently from other tags of the same time. I assume you are saying style sheets do that. Do you have to do the style sheet for each type of output? I would assume you do. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026
> Tatsuo, when I added SGML reference pages to the back of my book, I took
> the HTML-generated output from SGML and loaded that into LaTeX. I did
> have to do a few things:
>
> convert SGML to HTML
> html2latex
> add * to \subsection* ?
> remove \newline
> remove \backslash
> remove \begin_inset Figure { ? } to ?
> remove trailing space from Description
> no table conversion
> change $$ to $ $
> no SQL query conversion, all on one line , program listing and synopsis
> space-period and space-comma
>
> It actually was pretty quick. The fixes were more cleaning up strange
> conversion from HTML to LaTeX.
Looks nice, but I'm afraid I have to do all the work above for 489
HTML files:-)
What I'm doing now is trying to fix openjade. It is written in C++,
and I hate C++, no way...
--
Tatsuo Ishii
> > It actually was pretty quick. The fixes were more cleaning up strange > > conversion from HTML to LaTeX. > > Looks nice, but I'm afraid I have to do all the work above for 489 > HTML files:-) > > What I'm doing now is trying to fix openjade. It is written in C++, > and I hate C++, no way... I cat'ed them all together, pulled them up in an editor with macros, and went to town for a few hours. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026
> > 5) We have been working for translating docs into Japanese using
> > EUC_JP encoding. Converting to HTML is no problem, but we cannot
> > get correct results for sgml-> RTF conversion at all. The
> > translated docs are just not be able to read, showing random
> > characters. It seems that openjade supports multibyte encodings at
> > least according to their manuals, but I can not get it working. I
> > have asked to dssslist but I have not gotten usefull helps yet.
>
> Sorry you are seeing trouble. I missed seeing your traffic on the dsssl
> list to which I am subscribed; which one are you using?
dssslist@lists.mulberrytech.com
> > BTW, I see some odd results from the 7.1 HTML docs. For example, in
> > parser-stage.html,
> > "Figure \ref{parsetree} shows the parse tree..."
> > What is the "\ref{parsetree}"?
>
> Looks sort of like latex, eh? :)
>
> They are residual markup for graphics from Stephan's Master's Thesis
> which were never transcribed from the originals (gifs?) to a usable
> format.
>
> Through disk crashes, system upgrades, and a failed backup device I
> *may* no longer have his original tarball. Does anyone else?
That's too bad. Did it posted to one of our mailing list?
--
Tatsuo Ishii
Tatsuo Ishii <t-ishii@sra.co.jp> writes:
>> They are residual markup for graphics from Stephan's Master's Thesis
>> which were never transcribed from the originals (gifs?) to a usable
>> format.
>>
>> Through disk crashes, system upgrades, and a failed backup device I
>> *may* no longer have his original tarball. Does anyone else?
> That's too bad. Did it posted to one of our mailing list?
Before you get too excited about resurrecting the still-commented-out
portions of Stephan's documentation, bear in mind that it was written
for 6.3 or thereabouts, and large parts of it are now obsolete. In
particular, almost none of his union/intersect/except implementation
survives in 7.1.
regards, tom lane
On Thu, 19 Apr 2001, Tatsuo Ishii wrote: > > It actually was pretty quick. The fixes were more cleaning up strange > > conversion from HTML to LaTeX. > > Looks nice, but I'm afraid I have to do all the work above for 489 > HTML files:-) It's not all that bad. There's really only 486, the other three are gifs. :) Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 56K Nationwide Dialup from $16.00/mo atPop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
Tatsuo Ishii writes: > > Sorry you are seeing trouble. I missed seeing your traffic on the dsssl > > list to which I am subscribed; which one are you using? > > dssslist@lists.mulberrytech.com The mailing list you should be on is docbook-apps@lists.oasis-open.org (see http://lists.oasis-open.org), which is more about docbook processing and less about dsssl programming (since that won't help you). -- Peter Eisentraut peter_e@gmx.net http://funkturm.homeip.net/~peter
> > > Sorry you are seeing trouble. I missed seeing your traffic on the dsssl > > > list to which I am subscribed; which one are you using? > > dssslist@lists.mulberrytech.com > The mailing list you should be on is docbook-apps@lists.oasis-open.org > (see http://lists.oasis-open.org), which is more about docbook processing > and less about dsssl programming (since that won't help you). Ah, thanks for the tip. I've been on the dsssl list forever, and it *is* related to the toolset we are using. btw, I've poked a bit at the rtf generated for the reference pages, and have found that the rtf emits gratuitous "\keepn" flags (keep the paragraph with the *following* paragraph). If I use sed to change these to "\keep" flags (keep the paragraph itself together) then the pages look *much* better. Will experiment a bit more, but I'm on the road to an easier way to generate the reference pages. - Thomas
> > > Sorry you are seeing trouble. I missed seeing your traffic on the dsssl > > > list to which I am subscribed; which one are you using? > > > > dssslist@lists.mulberrytech.com > > The mailing list you should be on is docbook-apps@lists.oasis-open.org > (see http://lists.oasis-open.org), which is more about docbook processing > and less about dsssl programming (since that won't help you). Thanks. Seems I subscribed wrong list... -- Tatsuo Ishii