Thread: Docs reorganization

Docs reorganization

From
Peter Eisentraut
Date:
With the extra month I'd like to do the reorganization of the docs into
one <Set>, which was discussed a while ago.  Then we'd only have one HTML
set to build and don't have to ship redundant versions.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/


Re: Docs reorganization

From
Peter Eisentraut
Date:
Peter Eisentraut writes:

> With the extra month I'd like to do the reorganization of the docs into
> one <Set>, which was discussed a while ago.  Then we'd only have one HTML
> set to build and don't have to ship redundant versions.

Oh well, somebody was faster... :-)  When was the last time the following
was updated though?

    http://www.postgresql.org/docs/postgres/index.html

If we're already at that point then we can abandon the separate user.sgml,
etc. and make links across books, right?

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/


Re: Docs reorganization

From
Thomas Lockhart
Date:
> If we're already at that point then we can abandon the separate user.sgml,
> etc. and make links across books, right?

Uh, I don't think so. It is unrealistic to have a 6-800 page hardcopy
doc set as a single volume, so the individual docs should continue to be
built.

                      - Thomas

Re: Docs reorganization

From
Peter Eisentraut
Date:
Thomas Lockhart writes:

> > If we're already at that point then we can abandon the separate user.sgml,
> > etc. and make links across books, right?
>
> Uh, I don't think so. It is unrealistic to have a 6-800 page hardcopy
> doc set as a single volume, so the individual docs should continue to be
> built.

I think the idea was to take the RTF file and split it at the boundaries.
If I remember right then you already tried that and considered in
workable.

Otherwise this whole change would have been pointless because now the
integrated doc looks exactly like the individual ones only with an extra
title page.  Then we might as well get rid of that, but I think the intent
was to make them all into one set to enable cross-links.  I can't find the
original discussion right now (no archives of pgsql-docs available?) but I
thought that was the plan.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/


Re: Docs reorganization

From
Peter Eisentraut
Date:
I wrote:

> I can't find the original discussion right now (no archives of
> pgsql-docs available?) but I thought that was the plan.

http://www.postgresql.org/mhonarc/pgsql-docs/2000-06/msg00024.html

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/


Re: Docs reorganization

From
Thomas Lockhart
Date:
> > I can't find the original discussion right now (no archives of
> > pgsql-docs available?) but I thought that was the plan.
> http://www.postgresql.org/mhonarc/pgsql-docs/2000-06/msg00024.html

Right. I agreed to evaluate the results, but stopped short of agreeing
that this will be the One True Way.

                    - Thomas

Re: Docs reorganization

From
Peter Eisentraut
Date:
Thomas Lockhart writes:

> Right. I agreed to evaluate the results, but stopped short of agreeing
> that this will be the One True Way.

Okay, maybe I misinterpreted it.  I apologize.

Anyway, let's look ahead...  Seemingly the intergrated document is
somewhat redundant now, as it just combines the individual docs with a
spartanic title page.  I would suggest that we instead create a nice,
representative HTML title page by hand (with elephant pic, etc.) and don't
build the integrated document separately any more.  That saves disk
space/bandwidth, and confusion because of the different chapter numbering
etc.  We could also put the identical title page on the website; that
would increase the overall appearance of consistency in the docs.

Also, we might want to split out the developer's guide (as opposed to
programmer's guide).  The current integrated build already does that, and
it should probably happen in general, since the addressed audiences are
distinct.  I think we discussed this several times already, but we never
actually laid down a decisive word.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/


Re: Docs reorganization

From
Thomas Lockhart
Date:
> Anyway, let's look ahead...  Seemingly the intergrated document is
> somewhat redundant now, as it just combines the individual docs with a
> spartanic title page.  I would suggest that we instead create a nice,
> representative HTML title page by hand (with elephant pic, etc.) and don't
> build the integrated document separately any more.  That saves disk
> space/bandwidth, and confusion because of the different chapter numbering
> etc.  We could also put the identical title page on the website; that
> would increase the overall appearance of consistency in the docs.

Sounds good. I would like to try the same kind of title page for the
hardcopy docs, so perhaps we can do this within the sgml (but hand-built
html for the html docs is fine too).

> Also, we might want to split out the developer's guide (as opposed to
> programmer's guide).  The current integrated build already does that, and
> it should probably happen in general, since the addressed audiences are
> distinct.  I think we discussed this several times already, but we never
> actually laid down a decisive word.

That would be fine. I put them together originally only because each was
fairly small. But both have grown at least a little and you are right,
they are for distinct audiences.

                        - Thomas

Re: Re: Docs reorganization

From
The Hermit Hacker
Date:

I don't believe that that URL is applicable anymore ... Vince moved things
into the users-lounge, under a v7.0 vs v6.5.3 directory structure ...


On Sat, 30 Sep 2000, Peter Eisentraut wrote:

> Peter Eisentraut writes:
>
> > With the extra month I'd like to do the reorganization of the docs into
> > one <Set>, which was discussed a while ago.  Then we'd only have one HTML
> > set to build and don't have to ship redundant versions.
>
> Oh well, somebody was faster... :-)  When was the last time the following
> was updated though?
>
>     http://www.postgresql.org/docs/postgres/index.html
>
> If we're already at that point then we can abandon the separate user.sgml,
> etc. and make links across books, right?
>
> --
> Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/
>

Marc G. Fournier                   ICQ#7615664               IRC Nick: Scrappy
Systems Administrator @ hub.org
primary: scrappy@hub.org           secondary: scrappy@{freebsd|postgresql}.org


Re: Re: Docs reorganization

From
Vince Vielhaber
Date:
On Sat, 7 Oct 2000, The Hermit Hacker wrote:

>
>
> I don't believe that that URL is applicable anymore ... Vince moved things
> into the users-lounge, under a v7.0 vs v6.5.3 directory structure ...

I think the url is for the CURRENT docs.  When 7.1 hits the streets a
copy of it will be put in the user's lounge.

Vince.

>
>
> On Sat, 30 Sep 2000, Peter Eisentraut wrote:
>
> > Peter Eisentraut writes:
> >
> > > With the extra month I'd like to do the reorganization of the docs into
> > > one <Set>, which was discussed a while ago.  Then we'd only have one HTML
> > > set to build and don't have to ship redundant versions.
> >
> > Oh well, somebody was faster... :-)  When was the last time the following
> > was updated though?
> >
> >     http://www.postgresql.org/docs/postgres/index.html
> >
> > If we're already at that point then we can abandon the separate user.sgml,
> > etc. and make links across books, right?
> >
> > --
> > Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/
> >
>
> Marc G. Fournier                   ICQ#7615664               IRC Nick: Scrappy
> Systems Administrator @ hub.org
> primary: scrappy@hub.org           secondary: scrappy@{freebsd|postgresql}.org
>
>

--
==========================================================================
Vince Vielhaber -- KA8CSH    email: vev@michvhf.com    http://www.pop4.net
 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking
        Online Campground Directory    http://www.camping-usa.com
       Online Giftshop Superstore    http://www.cloudninegifts.com
==========================================================================