Skip site navigation (1) Skip section navigation (2)

Use of literal in SGML docs

From: Bruce Momjian <bruce(at)momjian(dot)us>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, PostgreSQL-documentation <pgsql-docs(at)postgresql(dot)org>
Subject: Use of literal in SGML docs
Date: 2011-09-05 15:51:35
Message-ID: 201109051551.p85FpZU05054@momjian.us (view raw or flat)
Thread:
Lists: pgsql-committerspgsql-docspgsql-hackers
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(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Robert Haas <robertmhaas(at)gmail(dot)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(at)momjian(dot)us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

In response to

Responses

pgsql-docs by date

Next:From: Bruce MomjianDate: 2011-09-05 15:56:03
Subject: Re: 'literal' for numbers
Previous:From: Bruce MomjianDate: 2011-09-03 23:09:27
Subject: Re: sgml cleanup: unescaped '>' characters

pgsql-hackers by date

Next:From: Bruce MomjianDate: 2011-09-05 15:56:03
Subject: Re: 'literal' for numbers
Previous:From: hubert depesz lubaczewskiDate: 2011-09-05 15:48:50
Subject: Re: [GENERAL] pg_upgrade problem

pgsql-committers by date

Next:From: Bruce MomjianDate: 2011-09-05 15:56:03
Subject: Re: 'literal' for numbers
Previous:From: Alvaro HerreraDate: 2011-09-05 15:07:12
Subject: Re: [COMMITTERS] pgsql: Clean up the #include mess a little.

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group