Use of literal in SGML docs
От | Bruce Momjian |
---|---|
Тема | Use of literal in SGML docs |
Дата | |
Msg-id | 201109051551.p85FpZU05054@momjian.us обсуждение исходный текст |
Ответ на | Re: [COMMITTERS] pgsql: remove tags. (Robert Haas <robertmhaas@gmail.com>) |
Ответы |
Re: Use of literal in SGML docs
(Robert Haas <robertmhaas@gmail.com>)
|
Список | pgsql-docs |
Did we want to do any more on the issue of using <literal> for numbers in our docs? The February thread is here: http://archives.postgresql.org/pgsql-docs/2011-02/msg00028.php While the applied patch removed the 'literal' tag from some numbers, we were not consistenly using 'literal' for constants in our docs. I can make the change if we decide what we consistently want, or maybe it is fine as-is. --------------------------------------------------------------------------- Robert Haas wrote: > On Mon, Feb 7, 2011 at 10:08 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > Robert Haas <robertmhaas@gmail.com> writes: > >> Which way did we more commonly do it before you applied this patch? > > > > We don't have a standard for this, and an undocumented patch applied > > without any discussion doesn't create one. ?It's hopeless to imagine > > that you'll ever achieve any uniformity that way. ?It won't last long > > if you do, since you're outnumbered by committers who won't be following > > whatever you think the convention is. > > > > I'm not even sure why you're trying --- I don't think it even makes > > sense to try to have a standard about this. ?I can easily imagine that > > integer constants might read better with <literal> in some contexts > > and better without in others. > > *reads patch more carefully* > > Here are my verdicts: > > advanced.sgml: good > array.sgml: good > backup.sgml: unsure > catalogs.sgml: bad > client-auth.sgml: bad > config.sgml: bad > func.sgml: bad > high-availability.sgml: bad > libpq.sgml: bad > runtime.sgml: bad > spi.sgml: unsure > tsearch2.sgml: good > > So I guess I'm back agreeing with you. Basically, it seems like we > ought to use <literal> if it's being used as a value that the user > might want to supply (e.g. "if you set this parameter to 0, then no > statements will be logged). It shouldn't use <literal> if it's just > being used as a number (e.g. "this query will return all airplanes > with a height of less than 30,000 feet"). The cases I'm unsure about > are the ones where we're talking about a return value (e.g. in the > event of an error, this function will return -1). > > -- > Robert Haas > EnterpriseDB: http://www.enterprisedb.com > The Enterprise PostgreSQL Company -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
В списке pgsql-docs по дате отправления: