[docs] xmldocs - jon modified refs/no_default_reparse
jon at endpoint.com
Sat Aug 20 15:34:47 EDT 2005
On Sat, 20 Aug 2005, Davor Ocelic wrote:
> The primary "rule" that you broke, however, is putting universally
> applicable style instructions into individual reference pages.
> See, users visiting the "no_default_reparse" pragma documentation
> will learn that *pragmas are best defined at the top of pages*,
> while users visiting all other pragma pages will not be told the same.
> Therefore, by nature, such information should be moved to 'pragma'
> glossary entry which, by definition, contains all information
> about pragmas.
That makes sense. The reason I did that is that you wrote "put the pragma
anywhere on the page". Why say that? Shouldn't "anywhere on the page" go
in the pragma entry as well? I'd prefer to say nothing, and expect people
to read up on how pragmas work.
Is there a problem with having two examples? Pragmas are so dirt-simple to
use that I don't know why you'd need any, really, but in this case I
wanted people to be on the lookout for it being set in catalog.cfg, since
we're likely going to do that in the Standard demo. What do you think?
> Second problem is, there are entity files in xmldocs/docbook/*.ent.
> It is always advisable to use entities instead of manual markup.
> For example, catalog.cfg should always be written as &ccf; ,
> this entity will expand to <filename>catalog.cfg</filename>.
> Likewise, interchange.cfg should be written as &gcf;.
> See docbook/*.ent files for a list of possible entities.
Ok, I'll take a look through the entity list.
More information about the docs