Reviewers: J_lowe,
http://codereview.appspot.com/6195098/diff/4023/Documentation/notation/input.itely File Documentation/notation/input.itely (right): http://codereview.appspot.com/6195098/diff/4023/Documentation/notation/input.itely#newcode1077 Documentation/notation/input.itely:1077: On 2012/05/17 17:53:17, J_lowe wrote:
I'm not comfortable with tables/lists like this in the NR. Yes I am
sure it
works for those that think like that, but for a user it's too
complicated.
@examples work much better.
I'm not disparaging the work you've done but from a documentation
point of view
I think 'we' (royal or otherwise) can do better for users.
I have a hard time understanding what should be wrong with explaining the arguments of the command one by one. The actual examples follow, and one can cross-check with the itemized overview. What you propose is omitting the complete and concise information, and forcing the user to gather and deduce this information manually from the examples. I don't see how this should be more helpful.
If this were the Application Usage manual then sure, but not the NR.
Examples
are much better.
The examples are _there_.
I spent an age getting this right personally from a doc point of view
last week
and I just don't think this is in the 'spirit' of the NR. Happy to get
another
opinion.
I don't presume that I have made a good match for the 'spirit' of the NR: I just have tried to make sure that the information is complete and correct. The interface to the functionality now is reasonably straightforward and logical, and the description is reasonably complete. For that reason, I would strongly suggest that you start a rewrite from _this_ data point instead of the previous state of the documentation, even if that means that you have to rework the style into everything. I think that is less error-prone than if you rework the technical details into the previous existing style.
If you don;t mind (because I know how personal this <> stuff had
become) I can
look at this part again over the weekend and use this to make a new
patch for
the doc myself?
Sure. But I would strongly suggest that the more technically inclined readers do not have to go treasure-hunting through a heap of examples in order to deduce the real deal. It is ok if the heap of examples is around for those who prefer that style. Description: Make \footnote work via \tweak Allow Tweak_engraver to take a (grob.property) pair as tweak address Revert "Merge branch 'footnote' into HEAD" This reverts commit 2ec0cd55d55c49dee4e5604903dfab8ff4a089c4, reversing changes made to 0a0274a3bf5792dfb7ce3719f5dfaef36059affe. Those are the three commits currently making up this issue. The music function \footnote, in addition to the arguments it already takes, now takes an additional music argument, either a chord constituent, or a music event on its own, or a postevent (in which case, like \tweak, you should invoke \footnote with an explicit event character - in front of it). The footnote is visible on any Grob directly caused by the following event in the source code (the additional music argument), unless a grob-name is specified, in which case it will appear on any grob of that type _ultimately_ caused by the following event (a Flag is directly caused by a NoteHead grob, but ultimately by a NoteEvent). I had been considering placing the anchoring Music event as first argument of \footnote. However, that makes for totally awful nesting syntax in case you attach several footnotes to the same Music. Please review this at http://codereview.appspot.com/6195098/ Affected files: M Documentation/de/notation/input.itely M Documentation/es/notation/input.itely M Documentation/fr/notation/input.itely M Documentation/ja/notation/input.itely M Documentation/notation/input.itely M input/regression/footnote-auto-numbering-page-reset.ly M input/regression/footnote-auto-numbering-vertical-order.ly M input/regression/footnote-auto-numbering.ly M input/regression/footnote-break-visibility.ly M input/regression/footnote-footer-padding.ly M input/regression/footnote-spanner.ly M input/regression/footnote.ly M input/regression/in-note.ly M lily/footnote-engraver.cc M lily/grob.cc M lily/parser.yy M lily/tweak-engraver.cc M ly/music-functions-init.ly M python/convertrules.py M scm/define-grob-properties.scm M scm/define-music-types.scm _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel