RE: LM 4 Tweaks vs. NR 6 Changing defaults

[Trevor Daniels]

The essential difference between the material in the
LM and the NR is the style in which it is presented.

The LM follows a pedagogical style with material
presented in a logical teaching order.  It is intended
to be read strictly sequentially, pretty much as a
course of study, by an early user wanting to understand
how to use LilyPond.  When read like this, everything is
explained before it is used (it's an documentation
error if it isn't), and material is presented roughly in
order of increasing complexity.  The examples used in LM 4
Tweaks are chosen to illustrate the points being made:
no attempt is made to give examples of the use of every
important property.

The NR should be written in a concise reference style,
designed to help (fairly) experienced users find the
information they need quickly and easily.  So material
is ordered logically by topic, sections are pretty much
self-contained, explanations (if any) are brief, the
index is well-designed, and everything of importance is
mentioned and easily found.

So, with regard to the Graham's questions about Tweaks:

No, the material in LM 4 Tweaks should not be duplicated
or moved to the NR as it is.  It is written in entirely
the wrong style and in the wrong order for a Reference
manual.  My view is that NR 6 Changing defaults should
be a strictly factual and comprehensive guide to the
IR: with explanations of, and links to, its major pages,
for example "The available contexts are listed in
@internalsref{..}", "All the layout objects can be found
in @internalsref{..}", together with sections explaining
how to use the important properties contained in the common
interfaces, like 'break-visibility, 'direction, 'color,
'X-extent, 'X-offset, 'extra..., 'minimum ..., 'padding,
etc, etc.  Particularly important are any exceptions to
general rules, like properties that are in a supported
interface but are ignored by a particular grob.  Also
the topics of Spanners, VerticalAxisGroup and other
esoteric topics are not mentioned in the LM and should
appear here in the NR.  Finally, the level of explanation
in NR 6 should assume the reader is familiar with the
generalities presented in LM 4 Tweaks, so there should be
little duplication in practice.

Trevor D



> -----Original Message-----
> From: address@hidden
> [mailto:lilypond-devel-bounces+t.daniels=treda.co.
> address@hidden Behalf
> Of Graham Percival
> Sent: 20 March 2008 01:50
> To: lily-devel
> Subject: LM 4 Tweaks vs. NR 6 Changing defaults
>
>
> It's time to start discussing what to do about
> tweaks and Changing
> defaults in the NR.
>
> LM 4 Tweaks has a lot of explanation about tweaks.
> - do we want to duplicate all of this, in a
> condensed form in the
>   NR?
> - should we just move LM 4 Tweaks into the NR to
> avoid harmful
>   duplication?
> - if we have other material to explain (like how
>   #'break-visibility works), should add this to
> the already-large
>   LM 4, or add it to NR 6 changing defaults?
>
> At the moment, I don't have any particular
> opinions about these
> issues.
>
> Cheers,
> - Graham
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel
>