Doc: Point-and-Click has wrong default value and ref to SVG output needs adding

Doc: Point-and-Click has wrong default value and ref to SVG output needs adding

Issue 3854

Also made sure that references to Point-and-click are consistent
through lily.scm and external.itely (including TexInfo formatting).

[lemzwerg, 2014-02-10 19:31:05]

https://codereview.appspot.com/61630045/diff/1/Documentation/usage/external.i...
File Documentation/usage/external.itely (right):

https://codereview.appspot.com/61630045/diff/1/Documentation/usage/external.i...
Documentation/usage/external.itely:32: in the @code{PDF} viewer.  This makes it
easier to find input that
I'm not sure it's a good idea to use @code for acronyms like PDF or SVG. 
Shouldn't we reserve this to commands and the like?

[ul_openlilylib.org, 2014-02-10 19:34:46]

lemzwerg@googlemail.com schrieb:
>
>https://codereview.appspot.com/61630045/diff/1/Documentation/usage/external.itely
>File Documentation/usage/external.itely (right):
>
>https://codereview.appspot.com/61630045/diff/1/Documentation/usage/external.itely#newcode32
>Documentation/usage/external.itely:32: in the @code{PDF} viewer.  This
>makes it easier to find input that
>I'm not sure it's a good idea to use @code for acronyms like PDF or
>SVG.
>  Shouldn't we reserve this to commands and the like?

I just came across this when wanting to write a repository name. If I understood
the section in the CG right @var would be the command of choice for this.

>
>https://codereview.appspot.com/61630045/
>
>_______________________________________________
>lilypond-devel mailing list
>lilypond-devel@gnu.org
>https://lists.gnu.org/mailman/listinfo/lilypond-devel


-- 
Urs Liska
openlilylib.org

[pkx166h, 2014-02-10 19:42:17]

On 2014/02/10 19:34:46, ul_openlilylib.org wrote:
> 
> mailto:lemzwerg@googlemail.com schrieb:
> >
>
>https://codereview.appspot.com/61630045/diff/1/Documentation/usage/external.itely
> >File Documentation/usage/external.itely (right):
> >
>
>https://codereview.appspot.com/61630045/diff/1/Documentation/usage/external.itely#newcode32
> >Documentation/usage/external.itely:32: in the @code{PDF} viewer.  This
> >makes it easier to find input that
> >I'm not sure it's a good idea to use @code for acronyms like PDF or
> >SVG.
> >  Shouldn't we reserve this to commands and the like?
> 
> I just came across this when wanting to write a repository name. If I
understood
> the section in the CG right @var would be the command of choice for this.
> 
> >
> >https://codereview.appspot.com/61630045/
> >
> >_______________________________________________
> >lilypond-devel mailing list
> mailto:>lilypond-devel@gnu.org
> >https://lists.gnu.org/mailman/listinfo/lilypond-devel
> 
> 
> -- 
> Urs Liska
> http://openlilylib.org

It's pretty inconsistent. What I have done is take @code{} of all the 'PDF' and
'SVG' and 'PS' references when talking about the file itself (or a viewer)
rather than say a file extension or (obviously) when using it in a command line.

James

[pkx166h, 2014-02-10 19:43:56]

Taken @code{} references off of PDF and SVG when referring to the file itself

[lemzwerg, 2014-02-10 20:53:03]

LGTM, thanks.

[Graham Percival, 2014-02-14 08:24:13]

LGTM

[Devon Schudy, 2014-02-14 10:24:08]

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
File Documentation/usage/running.itely (right):

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:409: SVG output should be compatible with any
SVG editor or user agent. There
Most users don't know the term “user agent”. Maybe “browser” or “viewer”
instead?

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:675: size increases in PDFfiles.
Missing space: “PDFfiles”

[dak, 2014-02-14 10:49:03]

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
File Documentation/usage/running.itely (left):

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:670: relevant when @code{PDF} is generated
from PostScript output
Maybe we should be using @acronym here?  It's used in several other places in
the docs so it is not that we don't support it.  It's not mentioned in our
coding guidelines.  Maybe it should?

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
File Documentation/usage/running.itely (right):

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:409: SVG output should be compatible with any
SVG editor or user agent. There
On 2014/02/14 10:24:08, Devon Schudy wrote:
> Most users don't know the term “user agent”. Maybe “browser” or “viewer”
> instead?

I don't understand what this is trying to get at.  First it says it "should" be
compatible with any SVG reader.  Then it mentions that you might want to try
some option for using different font files.  So it isn't compatible with any
reader?  Or what's the point?

At any rate, if a certain file format is produced, the expectation is that it is
useful for programs reading that format.  Short of any useful information to the
contrary, this sentence should just get removed.

[pkx166h, 2014-02-16 06:51:17]

Looking at the TexInfo page for @acronym

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040acronym.html

It doesn't seem to give us anything that useful and perhaps (as it also says in
the link above): 

- In general, it’s not essential to use either of these commands for all
abbreviations; use your judgment. Text is perfectly readable without them. 

So unless anyone has strong feelings - and we can have a new tracker - I think
I'll leave them unformatted.

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
File Documentation/usage/running.itely (right):

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:409: SVG output should be compatible with any
SVG editor or user agent. There
On 2014/02/14 10:24:08, Devon Schudy wrote:
> Most users don't know the term “user agent”. Maybe “browser” or “viewer”
> instead?

I Removed the sentence (see David's comment).

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:409: SVG output should be compatible with any
SVG editor or user agent. There
On 2014/02/14 10:49:04, dak wrote:
> On 2014/02/14 10:24:08, Devon Schudy wrote:
> > Most users don't know the term “user agent”. Maybe “browser” or “viewer”
> > instead?
> 
> I don't understand what this is trying to get at.  First it says it "should"
be
> compatible with any SVG reader.  Then it mentions that you might want to try
> some option for using different font files.  So it isn't compatible with any
> reader?  Or what's the point?
> 
> At any rate, if a certain file format is produced, the expectation is that it
is
> useful for programs reading that format.  Short of any useful information to
the
> contrary, this sentence should just get removed.

Done.

https://codereview.appspot.com/61630045/diff/20001/Documentation/usage/runnin...
Documentation/usage/running.itely:675: size increases in PDFfiles.
On 2014/02/14 10:24:08, Devon Schudy wrote:
> Missing space: “PDFfiles”

Done.

[pkx166h, 2014-02-16 06:52:35]

Devon and David's corrections.

[t.daniels_treda.co.uk, 2014-02-16 09:13:29]

pkx166h@gmail.com wrote Sunday, February 16, 2014 6:51 AM


> Looking at the TexInfo page for @acronym
> 
>
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040acronym.html
> 
> It doesn't seem to give us anything that useful and perhaps (as it also
> says in the link above):
> 
> - In general, it's not essential to use either of these commands for all
> abbreviations; use your judgment. Text is perfectly readable without
> them.
> 
> So unless anyone has strong feelings - and we can have a new tracker - I
> think I'll leave them unformatted.

I agree.  New doc writers are hard to come by and can be easily
put off by the complexity of TexInfo.  We should not complicate
things unnecessarily by yet more rules.

Trevor