Thread

7.1 docs

Tatsuo Ishii <t-ishii@sra.co.jp> — 2001-03-23T08:50:44Z

I have a plan to translate 7.1 docs into Japanases and I looked around
current docs. I noticed that contacts.sgml and ref/current*.sgml are
not used anywhere in the result html nor in man pages.
Does anybody know the reason? Or am I missing something?
--
Tatsuo Ishii

Re: 7.1 docs

Thomas Lockhart <lockhart@alumni.caltech.edu> — 2001-03-23T14:51:33Z

> I have a plan to translate 7.1 docs into Japanases and I looked around
> current docs. I noticed that contacts.sgml and ref/current*.sgml are
> not used anywhere in the result html nor in man pages.
> Does anybody know the reason? Or am I missing something?

I put in contacts.sgml a *long* time ago, thinking that something like
it should be in the docs. But it was not complete enough to consider
including at the time (now that I look, it only has my name ;), so it
was only a placeholder for the future.

We could take it out altogether if we want. Peter?

The ref/current_{date,time...}.sgml files are there because (a)
functions should be documented, and (b) someone documented them. But we
never documented enough functions to justify setting up an entire
section of a manual to cover them. I think that these are more likely to
be used in the future, but we do need additional pages written covering
other functions.

                  - Thomas

Re: Re: 7.1 docs

Tatsuo Ishii <t-ishii@sra.co.jp> — 2001-03-23T15:06:05Z

> > I have a plan to translate 7.1 docs into Japanases and I looked around
> > current docs. I noticed that contacts.sgml and ref/current*.sgml are
> > not used anywhere in the result html nor in man pages.
> > Does anybody know the reason? Or am I missing something?
> 
> I put in contacts.sgml a *long* time ago, thinking that something like
> it should be in the docs. But it was not complete enough to consider
> including at the time (now that I look, it only has my name ;), so it
> was only a placeholder for the future.
> 
> We could take it out altogether if we want. Peter?
> 
> The ref/current_{date,time...}.sgml files are there because (a)
> functions should be documented, and (b) someone documented them. But we
> never documented enough functions to justify setting up an entire
> section of a manual to cover them. I think that these are more likely to
> be used in the future, but we do need additional pages written covering
> other functions.

Oh I see. Thanks for the explanation.
--
Tatsuo Ishii

Re: Re: 7.1 docs

Roberto Mello <rmello@cc.usu.edu> — 2001-03-23T15:25:22Z

On Fri, Mar 23, 2001 at 02:51:33PM +0000, Thomas Lockhart wrote:
> 
> The ref/current_{date,time...}.sgml files are there because (a)
> functions should be documented, and (b) someone documented them. But we
> never documented enough functions to justify setting up an entire
> section of a manual to cover them. I think that these are more likely to

	This is one of the reasons why I created the PostgreSQL CookBook
project. The documentatin of PG function is really small, with barely any
examples.
	It looks like either the PG community does not write/use functions or
very few people are willing to take 5 minutes and contribute an example
for a function. So far (after over a week) the CookBook has 8 recipes 
posted.
	For those wondering, the cookbook project is at
http://www.brasileiro.net/postgres. I plan to post a slew of functions 
from the OpenACS project sometime next week.

	-Roberto
-- 
+----| http://fslc.usu.edu USU Free Software & GNU/Linux Club|------+
  Roberto Mello - Computer Science, USU - http://www.brasileiro.net 
      http://www.sdl.usu.edu - Space Dynamics Lab, Web Developer    
WHeRe is ThaT DArN ShIfT keY?

Re: 7.1 docs

Peter Eisentraut <peter_e@gmx.net> — 2001-03-24T11:01:43Z

Tatsuo Ishii writes:

> I have a plan to translate 7.1 docs into Japanases

Btw...

One thing I am thinking about doing for the 7.2 cycle is set up the
doc/src/ directory in a way to keep translations in tree.  It would
probably look something like:

doc/src/
    sgml/	-- original (implicitly en_US)
    en_GB/	-- translation
    de_DE/	-- translation
    ...

This way (or at least the way I'm imagining it) you would make a directory
for you language, copy the file over that you want to translate, and edit
it there.  When you build, all the files that you haven't done will be
picked up from the original.

How does that sound?

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

Re: 7.1 docs

Peter Eisentraut <peter_e@gmx.net> — 2001-03-24T12:48:35Z

Thomas Lockhart writes:

> I put in contacts.sgml a *long* time ago, thinking that something like
> it should be in the docs. But it was not complete enough to consider
> including at the time (now that I look, it only has my name ;), so it
> was only a placeholder for the future.

The "Resources" prefix section has contact info.  The rest is on the web
site.

> The ref/current_{date,time...}.sgml files are there because (a)
> functions should be documented, and (b) someone documented them. But we
> never documented enough functions to justify setting up an entire
> section of a manual to cover them. I think that these are more likely to
> be used in the future, but we do need additional pages written covering
> other functions.

All functions are documented (for appropriate values of "all") in the
User's Guide, chapter 4.  There was probably once the idea of setting up a
reference page set for the functions, but I don't know if this is
particularly better than what we have now.  In fact, I would argue it's
worse.

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

Re: [HACKERS] Re: 7.1 docs

Tom Lane <tgl@sss.pgh.pa.us> — 2001-03-24T16:32:02Z

Peter Eisentraut <peter_e@gmx.net> writes:
> All functions are documented (for appropriate values of "all") in the
> User's Guide, chapter 4.  There was probably once the idea of setting up a
> reference page set for the functions, but I don't know if this is
> particularly better than what we have now.  In fact, I would argue it's
> worse.

A "page per function" approach is clearly overkill for the vast majority
of our functions.  I think that's not unrelated to the fact that no one's
ever bothered to prepare such documentation ;-)

On the other hand, the existing layout of the User's Guide encourages a
"line per function" approach, which is insufficient for at least some
functions.  We've worked around that by adding paragraphs below the main
table on each page, but that seems a little awkward in many cases.

A reference section in the style of typical Unix section-3 man pages
(multiple related functions per page, with text discussion and examples)
would be a useful compromise, maybe.  Needs more thought.

			regards, tom lane

Re: 7.1 docs

Tatsuo Ishii <t-ishii@sra.co.jp> — 2001-03-25T00:48:43Z

> Tatsuo Ishii writes:
> 
> > I have a plan to translate 7.1 docs into Japanases
> 
> Btw...
> 
> One thing I am thinking about doing for the 7.2 cycle is set up the
> doc/src/ directory in a way to keep translations in tree.  It would
> probably look something like:
> 
> doc/src/
>     sgml/	-- original (implicitly en_US)
>     en_GB/	-- translation
>     de_DE/	-- translation
>     ...
> 
> This way (or at least the way I'm imagining it) you would make a directory
> for you language, copy the file over that you want to translate, and edit
> it there.  When you build, all the files that you haven't done will be
> picked up from the original.
> 
> How does that sound?

That is almost what I am thinking:-) Sounds like a good idea. 

Another thing what we should care about is man pages. Is there any
standard way to coexist multiple languages under /usr/man? I see "ja"
subdirectory under it in my localized version of Linux.
--
Tatsuo Ishii

Re: 7.1 docs

Marc G. Fournier <scrappy@hub.org> — 2001-03-25T01:02:38Z

On Sun, 25 Mar 2001, Tatsuo Ishii wrote:

> > Tatsuo Ishii writes:
> >
> > > I have a plan to translate 7.1 docs into Japanases
> >
> > Btw...
> >
> > One thing I am thinking about doing for the 7.2 cycle is set up the
> > doc/src/ directory in a way to keep translations in tree.  It would
> > probably look something like:
> >
> > doc/src/
> >     sgml/	-- original (implicitly en_US)
> >     en_GB/	-- translation
> >     de_DE/	-- translation
> >     ...
> >
> > This way (or at least the way I'm imagining it) you would make a directory
> > for you language, copy the file over that you want to translate, and edit
> > it there.  When you build, all the files that you haven't done will be
> > picked up from the original.
> >
> > How does that sound?
>
> That is almost what I am thinking:-) Sounds like a good idea.
>
> Another thing what we should care about is man pages. Is there any
> standard way to coexist multiple languages under /usr/man? I see "ja"
> subdirectory under it in my localized version of Linux.

we have similar on FreeBSD ... /usr/share/man/ja ...

Re: 7.1 docs

Weiping He <laser@zhengmai.com.cn> — 2001-03-25T02:08:14Z

Peter Eisentraut wrote:

> Tatsuo Ishii writes:
>
> > I have a plan to translate 7.1 docs into Japanases
>
> Btw...
>
> One thing I am thinking about doing for the 7.2 cycle is set up the
> doc/src/ directory in a way to keep translations in tree.  It would
> probably look something like:
>
> doc/src/
>     sgml/       -- original (implicitly en_US)
>     en_GB/      -- translation
>     de_DE/      -- translation
>     ...
>
> This way (or at least the way I'm imagining it) you would make a directory
> for you language, copy the file over that you want to translate, and edit
> it there.  When you build, all the files that you haven't done will be
> picked up from the original.
>
> How does that sound?
>

Wonderful! I think I can provide en_GB encoding translations.
May be because there are lack of some software package, I still can't
generate other format (html, ps etc.) on my machine after upgrade to 7.1,
but the old Makefile is ok. don't know why, if put up there, then you can
generate other format without problem.

Thanks & Regards

Laser Henry

Re: Re: [HACKERS] Re: 7.1 docs

Roberto Mello <rmello@cc.usu.edu> — 2001-03-25T16:23:10Z

On Sat, Mar 24, 2001 at 11:32:02AM -0500, Tom Lane wrote:
> 
> A "page per function" approach is clearly overkill for the vast majority
> of our functions.  I think that's not unrelated to the fact that no one's
> ever bothered to prepare such documentation ;-)

	Agreed.
 
> On the other hand, the existing layout of the User's Guide encourages a
> "line per function" approach, which is insufficient for at least some
> functions.  We've worked around that by adding paragraphs below the main
> table on each page, but that seems a little awkward in many cases.

	Again I agree. The functions docs are insufficient for most functions
I would say.
	I like the way the Oracle functions are documented, except for the
fact that they have one huge page for all functions, which is hard on
those on slow connections reading docs online. 
	They have functions in tables grouped per functionality (e.g. character
functions that returning character values, character functions returning
number values) and with each function name (which is all that is in the
table) is linked to a larger explanation of the function with the complete
syntax and examples (usually two).
	http://oradoc.photo.net/ora81/DOC/server.815/a67779/function.htm#1028572

	-Roberto	
-- 
+----| http://fslc.usu.edu USU Free Software & GNU/Linux Club|------+
  Roberto Mello - Computer Science, USU - http://www.brasileiro.net 
      http://www.sdl.usu.edu - Space Dynamics Lab, Web Developer    
If it wasn't for C, we would be using BASI, PASAL and OBOL!

Re: Re: [HACKERS] Re: 7.1 docs

Tom Lane <tgl@sss.pgh.pa.us> — 2001-03-25T16:38:44Z

Roberto Mello <rmello@cc.usu.edu> writes:
> 	I like the way the Oracle functions are documented, except for the
> fact that they have one huge page for all functions, which is hard on
> those on slow connections reading docs online. 
> 	They have functions in tables grouped per functionality (e.g. character
> functions that returning character values, character functions returning
> number values) and with each function name (which is all that is in the
> table) is linked to a larger explanation of the function with the complete
> syntax and examples (usually two).

Yes, it'd be cool to have the User's Guide contain the existing function
tables with each entry hotlinked to a more extensive reference entry.
We could eliminate some of the nitty-gritty details from the User's
Guide that way, which I think is good.  I don't want to reduce the
function tables to just names a la Oracle --- I think the tables are
good as they are.  But there are places, such as in the discussion of
the pattern-match functions, where we have reference-page-like material
that doesn't fit very well in the U.G.

			regards, tom lane

Re: 7.1 docs

Peter Eisentraut <peter_e@gmx.net> — 2001-03-26T17:31:44Z

He Weiping(Laser Henry) writes:

> Wonderful! I think I can provide en_GB encoding translations.

en_GB would be a "British English" translation.  I don't think this is
what you wanted to do.

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

Re: 7.1 docs

Weiping He <laser@zhengmai.com.cn> — 2001-03-27T14:54:53Z

>
> en_GB would be a "British English" translation.  I don't think this is
> what you wanted to do.
>

cn_GB, sorry. :-D

Regards

Laser Henry