Обсуждение: Tips needed for contrib doc
Hi,
I wanted to spend a week or so putting the contrib doc into shape so I want
to start by moving the contrib part from a new appendix to the Reference
part.
The problems I find are:
- I can't make this "contrib" doc a part because Reference already is a part
and can't be nested.
Structure:
<part id="reference">
<part id="contrib">
- If I make the contrib doc a chapter in the index shows with an arabic
number not as a roman one.
Structure:
<part id="reference">
<chapter id="contrib">
- I can't make the doc a <reference> because first I need to point to the
modules and not all of them are documented like a reference.
Structure:
<part id="reference">
<reference id="contrib">
- If I leave it as it is now [1] the problem is that very small chapters just
don't look right IMHO. Take a look at [2], for example. It should be a module
per page in most cases except very long ones.
Structure:
<part id="contrib">
<chapter id="adminpack">
Does anyone have a solution on this? I'm no docbook expert, so I might be very
wrong.
[1] You can find the current state at
http://www.nan-tic.com/ftp/pgdoc-0.0.2/index.html
[2] http://www.nan-tic.com/ftp/pgdoc-0.0.2/adminpack.html
--
Albert Cervera i Areny
http://www.NaN-tic.com
Hi, Albert Cervera i Areny a écrit : > I wanted to spend a week or so putting the contrib doc into shape so I want > to start by moving the contrib part from a new appendix to the Reference > part. > The problems I find are: > - I can't make this "contrib" doc a part because Reference already is a part > and can't be nested. > Structure: > <part id="reference"> > <part id="contrib"> > > - If I make the contrib doc a chapter in the index shows with an arabic > number not as a roman one. > Structure: > <part id="reference"> > <chapter id="contrib"> > > - I can't make the doc a <reference> because first I need to point to the > modules and not all of them are documented like a reference. > Structure: > <part id="reference"> > <reference id="contrib"> > I think this is the better way to do it. Even if it means to rewrite the README to look like a reference. > - If I leave it as it is now [1] the problem is that very small chapters just > don't look right IMHO. Take a look at [2], for example. It should be a module > per page in most cases except very long ones. > Structure: > <part id="contrib"> > <chapter id="adminpack"> > > Does anyone have a solution on this? I'm no docbook expert, so I might be very > wrong. > The only (or simplest) way to have one page per module is to use the reference part. Regards. -- Guillaume. http://www.postgresqlfr.org http://dalibo.com
Guillaume Lelarge <guillaume@lelarge.info> writes:
> The only (or simplest) way to have one page per module is to use the
> reference part.
If the plan is one module per page, why not handle 'em just like the
current command and client reference pages? Add another list to
reference.sgml, and away you go.
regards, tom lane
The problem with this approach is dblink[1], for example, in which I can't use reference (as I've already used for dblink itself). I will probably have to use <refsect> in theses cases then... [1] http://www.nan-tic.com/ftp/pgdoc/dblink.html A Dijous 11 Octubre 2007, Tom Lane va escriure: > Guillaume Lelarge <guillaume@lelarge.info> writes: > > The only (or simplest) way to have one page per module is to use the > > reference part. > > If the plan is one module per page, why not handle 'em just like the > current command and client reference pages? Add another list to > reference.sgml, and away you go. > > regards, tom lane -- Albert Cervera i Areny http://www.NaN-tic.com
Am Mittwoch, 10. Oktober 2007 schrieb Albert Cervera i Areny: > - I can't make this "contrib" doc a part because Reference already > is a part and can't be nested. The Reference things in DocBook are mostly to support legacy man pages, and man pages are not necessary the greatest format to document everything. What is your reason that you want this as a reference rather than a part with chapters? -- Peter Eisentraut http://developer.postgresql.org/~petere/
Not that I want to make each module a reference. With previous discussions we seemed to agree that: - It should go into the References part of the documentation (right after "III. PostgreSQL Server Applications). - Each module docs should be in a single page, mainly because some contrib modules have/require very little documentation. So it seems that the only way of achieving both things is to make each contrib module a <refentry> inside a new <reference id="contrib">. I don't like this idea, among other things because dblink won't be abe to be treated as a <reference> which I think is appropiate in this case. If you've got another solution for this, it'll be very welcome! A Divendres 12 Octubre 2007, Peter Eisentraut va escriure: > Am Mittwoch, 10. Oktober 2007 schrieb Albert Cervera i Areny: > > - I can't make this "contrib" doc a part because Reference > > already is a part and can't be nested. > > The Reference things in DocBook are mostly to support legacy man pages, and > man pages are not necessary the greatest format to document everything. > What is your reason that you want this as a reference rather than a part > with chapters? -- Albert Cervera i Areny http://www.NaN-tic.com
Albert Cervera i Areny wrote: > Not that I want to make each module a reference. With previous > discussions we seemed to agree that: > > - It should go into the References part of the documentation (right > after "III. PostgreSQL Server Applications). > - Each module docs should be in a single page, mainly because some > contrib modules have/require very little documentation. It think you should structure the documentation by content, not by output format. You could make each module a section or a chapter, as you choose. -- Peter Eisentraut http://developer.postgresql.org/~petere/
The problem is that if we want these docs in the Reference section of the documentation right after "PostgreSQL Server Applications" they can't be chapters nor sections, they need to be <refentry>'s. That's the problem... A Diumenge 14 Octubre 2007, Peter Eisentraut va escriure: > Albert Cervera i Areny wrote: > > Not that I want to make each module a reference. With previous > > discussions we seemed to agree that: > > > > - It should go into the References part of the documentation (right > > after "III. PostgreSQL Server Applications). > > - Each module docs should be in a single page, mainly because some > > contrib modules have/require very little documentation. > > It think you should structure the documentation by content, not by > output format. You could make each module a section or a chapter, as > you choose. -- Albert Cervera i Areny http://www.NaN-tic.com
Albert Cervera i Areny <albert@nan-tic.com> writes:
> The problem is that if we want these docs in the Reference section of the
> documentation right after "PostgreSQL Server Applications" they can't be
> chapters nor sections, they need to be <refentry>'s. That's the problem...
In any case one would think that each contrib module should be at the
same logical level in the docs --- if some of them are only sections,
what chapter are they inside of?
One point here is that a lot of the contrib material is not really
written in reference style anyway. I wonder if the best solution is
to make it a separate <part>, with each contrib module being a
<chapter>, and then sections and subsections if needed.
regards, tom lane
Albert Cervera i Areny wrote: > The problem is that if we want these docs in the Reference section of > the documentation right after "PostgreSQL Server Applications" they > can't be chapters nor sections, they need to be <refentry>'s. That is not true, AFAICT. What do you base this assertion on? -- Peter Eisentraut http://developer.postgresql.org/~petere/
A Diumenge 14 Octubre 2007, Peter Eisentraut va escriure: > Albert Cervera i Areny wrote: > > The problem is that if we want these docs in the Reference section of > > the documentation right after "PostgreSQL Server Applications" they > > can't be chapters nor sections, they need to be <refentry>'s. > > That is not true, AFAICT. What do you base this assertion on? You're right, that's not exactly true: Reference is a Part. If we still want contrib inside Reference, contrib can be a <chapter>, <reference> or other elements defined at http://www.docbook.org/tdg5/en/html/part.html. But I cant' make the contrib section a <part> inside reference (that means no chapter per module!). If I make it a chapter the numbering inside Reference becomes: "I. SQL Commands" "II. PostgreSQL Client Applications" "III. PostgreSQL Server Applications" "43. Standard Modules" Not sure if that's a problem, but that's why I'm asking. That allows, however, having each contrib module in a section in this chapter and thus fits in one page. Though I agree I should concentrate on content, not style, having lots of very small pages isn't very nice either. You can see that in the docs I have online. In that case each module is a chapter as Tom suggests and it's a completely new Part after "Internals" IMHO having it in reference would make sense if contrib docs where organized like, well... references but that's not the case for most of them. After all you need some introduction to the module, some examples, etc. -- Albert Cervera i Areny http://www.NaN-tic.com
Given some of the problems I exposed earlier and the fact that the documentation of contrib modules isn't organized as a reference. I will be adding a new chapter to the "II. The SQL Language" part probably after "Full Text Search". This will also allow to have each module in one page as desired. Objections? A Dimecres 10 Octubre 2007, Albert Cervera i Areny va escriure: > Hi, > I wanted to spend a week or so putting the contrib doc into shape so I > want to start by moving the contrib part from a new appendix to the > Reference part. -- Albert Cervera i Areny http://www.NaN-tic.com
Albert Cervera i Areny <albert@nan-tic.com> writes:
> Given some of the problems I exposed earlier and the fact that the
> documentation of contrib modules isn't organized as a reference. I will be
> adding a new chapter to the "II. The SQL Language" part probably after "Full
> Text Search". This will also allow to have each module in one page as
> desired.
> Objections?
That seems like an entirely random place for it.
If you don't want to put it under Reference, maybe a new top-level Part
(probably after Reference) would be appropriate?
regards, tom lane