TOC for Musescore Handbook
After a lifetime of working with technical documents, I found it useful to have a TOC for the Musescore Handbook. I could not determine what package had been used to write the handbook so I created a TOC using the facility available in Microsoft Word formal document template. This created a numbered document (normal for technical publications, and resulted in a numbered TOC. I reduced this to a non-numbered TOC to match the format of the current handbook. On enquiry to Musescore, I was advised that there was interest in seeing these, so PDF files are attached. I would be hgappy to assist in any further development of the handbook.
Allan Carpenter
| Attachment | Size |
|---|---|
| Musescore contents - no numbering.pdf | 227.59 KB |
| Musescore contents - numbered.pdf | 230.11 KB |
Comments
The PDF of the handbook is created from the HTML. The HTML is edited on http://musescore.org in a wiki way. For english, this page is used. The HTML is processed with a python script named ProcessHTML.py. It uses XHTML2PDF to do the actual PDF 2 HTML transformation.
Unfortunaly, the TOC you made might be obsolete as soon as a new version of the PDF handbook is generated. I have no idea if XHTML2PDF can generate a TOC but if you are welcome to take a look if you wish.
A manual without neither TOC nor index has limited value. I understand that the existing tool is incapable of creating these (and automatically-generated indices are of low value anyway). However that doesn't change the situation: To be taken seriously, MuseScore needs a good up to date manual with both a TOC and index. I think this should have a relatively high priority, as people look for development projects. As the documentation expands, we increasingly see new users being hampered by not discovering existing features.
In reply to TOC and index seem fundamental by spinality
For MuseScore 2.0, there will be a rewrite of the current handbook. While we are doing this, we'll be using special markup so we can automatically create a TOC for the handbook. Hope this sounds good.
In reply to Handbook 2.0 by Thomas
Wonderful, thanks. So many issues seem to fall under the blanket of "it will be addressed in 2.0"!
In reply to TOC and index seem fundamental by spinality
For the record, there *is* a TOC - but only online, since it is a list of links, not page numbers.
And yes, I too would love to see more comprehensive documentation for 2.0, and hope to be able to help in that endeavor.
In reply to For the record, there *is* a by Marc Sabatella
These serve very different functions. I'm not a programmer - I don't really appreciate the differences in the various methods for marking a document - but if, for example, I want to find out how to make a little more room for lyrics by moving a measure from the 3rd staff to the 4th (and, obviously, shifting the layout for the rest of the piece), it's a lot easier to look up what I think are keywords in an index than to scroll through the whole TOC.
I do understand the difficulty of creating an index that includes enough synonyms to help even neophytes but - especially as you want this to be used in schools - for the user, the feature only exists if s/he can find it and learn how to use it.
Having complained (well, "commented"), I will throw my name into the pile of people who would be willing to help. Admittedly, I'm only a singer - and a bass at that - so not all that much can be expected (At least I'm not a soprano!) (Sorry - chorister joke.) but if I can help I will.
In reply to TOC and index by Roger Priddle
And good music!
Add to profile a bit more (country, operating system) and get familiar with the handbook, there is a lot of work on the horizon.
Ciao, Franz
In reply to TOC and index by Roger Priddle
"It's a lot easier to look up what I think are keywords in an index than to scroll through the whole TOC."
It's then even easier to user the search box on MuseScore.org, or to use google or Ctrl + F on the PDF handbook.
In reply to "It's a lot easier to look up by [DELETED] 5
Although using a text search or PDF ctrl-F is certainly easy, that serves a different purpose from a (properly assembled) index. An index should not be simply a generated list of every place a keyword appears; such cross-references are not very useful. A good index lists just the most important places where a given topic is addressed in depth. It's more like an alphabetical table of contents. Creating one is a significant task; publishers devote considerable resources to building indices for textbooks, scholarly works, references, etc.
This is a follow up comment on the effort to offer a PDF version of the handbook featuring a Table of Contents. You can find out about the current status at http://musescore.org/en/node/47941#comment-230991
@Allan I very much like the styling you have achieved with your table of contents, so with a variable vertical spacing between the headings. I miss this styling currently in my toc and I'm looking for someone who can help me out with this. Basically the toc can be styled via an xsl stylesheet as explained the wkhtmltopdf docs. If someone feels up to the task, please don't hesitate to help.