Update the manual

[uliska]

Now we have a proper manual in place we have to fill in the gaps, i.e. document the current state of the package. This should have kind of priority, i.e. new features should not be implemented at a faster pace than existing features are documented ;-)

Now that the manual is more or less complete we have to review it. Relevant questions are:

• Is everything documented?
• Are the explanations understandable?
• Are they consistent with the actual behaviour?
  • If not: should the manual be updated or the behaviour fixed?

To keep track of the progress here's a check list. Please update the issue (rather than commenting) by checking items and indicating when you are going to work on any sections. Add commits to the update-manual branch.

<many checked options deleted> Do we need example files for the following topics?

• [ ] Score layout / dimensions
• [ ] Protrusion (@uliska will move the existing examples to a separate file)
• [ ] Vertical alignment of fullpage scores
• [ ] Staff display options (notime etc.)
• [ ] relative
• [ ] verbatim

[uliska]

I have already pushed "something". I suggest we don*'t do this with individual pull requests, as I have the impression this produces too much overhead through unnecessary politeness.

Rather we should simply push new sections to that branch, allowing the others to add comments or simply apply edits on top. Maybe we can go through a final round of review and discussion when all the boxes aboive have been checked.

[jperon]

I agree with those suggestions. That said, I'm afraid I won't be able to help much next days, as I'll be quite busy for about a week.

[uliska]

I've went through the list of defined options and compared them to the index in the manual. So there's a number of small and not-so-small items to be documented.

@jperon could you maybe go ahead and document some of the remaining options that you implemented? I'll now turn to the horizontal alignment/protrusion issue.

[jperon]

Just done; I did this in several commits so that you may easier proofread if you want to.

[uliska]

@jperon I have updated the issue description with a new set of checkbox items, questions I came up with when reading through and reviewing the manual.

[jperon]

Stop on failed LilyPond compilation. I would like to review the decision to actually trigger an error here. While I agree that this is a very important message I find the stacktrace to be confusing. While it is of course "correct" it leads the user to suspect a programming error somewhere in the functions listed in the trace.

I don't think it's worth struggling about that:

• the trace mentions in function 'is_compiled_without_error', which can quite easily lead to the conclusion that it's a wanted result;
• if someone needs help, it will incite to submit an issue here, and the stacktrace will clearly indicate us from where the problem comes.

I think the maximum we could do is to be even more explicit in the message to state that the error comes from LilyPond; but even without it, I think it's clear enough.

[uliska]

@jperon I added a new list of question whether certain topics should get an example file

[jperon]

IMHO this shouldn't be blocking for release: the doc is explicit enough, and we can do that after.

[uliska]

Then maybe we should merge the manual branch now and give the package to some testers and the mailing lists before packageing a beta release?

[jperon]

If you agree with the last commit I pushed, OK for me.

[uliska]

Am 1. März 2018 17:33:43 MEZ schrieb jperon notifications@github.com:

If you agree with the last commit I pushed, OK for me.

Just left home, I'll look later.

Best Urs -- Diese Nachricht wurde von meinem Android-Gerät mit K-9 Mail gesendet.

[fedelibre]

Can you add the Documentation label to this issue?

I suggest to elaborate the part in the manual where you suggest not to run lualatex from a different directory from the source file. I want to do that, because I'm using Meson, a build tool which always builds out of source tree. So far I managed to make it work with the following workarounds:

1. includepaths={..}: tell lyluatex to search the parent directory.
2. If the book contain figures, I enter only the name of the files, then I set two paths, e.g.: \graphicspath{{images/}{../images/}}. So images will be found either way.