RE: gEDA-user: `' in PCB documentation confusing

["Robert Thorpe" <Robert.Thorpe@xxxxxxxxxxxx>]

> -----Original Message-----
> From: owner-geda-user@xxxxxxxx 
> [mailto:owner-geda-user@xxxxxxxx] On Behalf Of Lucas Vogelsang
> Sent: 20 November 2005 20:51
> To: geda-user@xxxxxxxx
> Subject: Re: gEDA-user: `' in PCB documentation confusing
> 
> On Sun, 2005-11-20 at 13:49 -0500, DJ Delorie wrote:
> > > I have just seen my friend to look up the ChangeDrillSize 
> command in 
> > > the PCB doc and type it. He typed `ChangeDrillSize(...)' because 
> > > that was written in the manual. It didn't work although he typed 
> > > *exactly* according to the manual.
> > 
> > So, the fact that there was an example there that didn't have the 
> > quotes didn't help?  Did he *exactly* type all the square 
> brackets and 
> > sample argument names too?
> > 
> '' is not used as a regex so there isn't any reason why one 
> shouldn't copy it...
> > I don't think there's much we can do about people who 
> blindly follow 
> > documentation without a little bit of thinking.  I suppose we could 
> > add *more* examples, but if the one that's already there 
> doesn't help, 
> > two won't help either.  Yes, I note that the example there is for a 
> > different command.  Still, there's plenty of examples 
> there, and none 
> > include the quotes.  Plus, the X manual documents the translation 
> > syntax in great detail, all we're doing is listing the functions we 
> > make available.
> > 
> If I write a documentation I don't write all the commands in 
> ".(see php.net/print for e.g.).
> > > I suggest the `' to be removed from the manual because they are 
> > > confusing.
> > 
> > We don't put them there.  The typesetting software puts them there.
> > All we put in is this:
> > 
> So one should change the typesetting software...

FWIW I think that examples should be surrounded by quotes.  I have
rarely read a manual of a piece of open-source/free software where they
are not.  It's what people expect.

If the quotes are not appropriate for some entities in some markup
outputs then they should be removed by generating that phrase with a
macro.  For outputs where they aren't appropriate the macro generates no
quotes.  This allows quotes to be used in other output forms where they
are appropriate.

Rob