Handbook 2.0 collaboration

• Oct 9, 2014 - 11:47

This is a call towards all beta 2.0 users who like to join the effort of creating an updated version of the MuseScore [[nodetitle:handbook]] . For those who helped with the 1.x handbook, make sure you read on as there are a couple of changes being introduced.

Starting point is the index page at http://musescore.org/en/node/35711 which is copied over from 1.x.
To add a new page to this index, first create the new page via http://musescore.org/en/node/add/book2 and next add it to the index following this formatting "[node:id]" with id the number of the page. So a new filter is introduced to link to handbook 2.0 pages.

Also new is the introduction of the Markdown filter. HTML will not be allowed anymore but instead use the markdown filter. There is one exception with is the "kbd" and "samp" html element for which there is no markdown 1.0.1 equivalent.

So to sum the 2.0 handbook effort:

  • update all the handbook pages listed at http://musescore.org/en/node/35711
  • replace html with Markdown filter, except for "kbd" and "samp". When replace header elements (h1, h2, ...), add an anchor to it like ###header-title {#header-title-anchor}. This will give the header an anchor link for deeplinking into the handbook page.
  • replace the [ [ ] ] filter with Markdown filter which is [title](external-url). If it's an internal link pointing to a page on musescore.org, use [node:id,title="title of the page you link to for accessibility and editing readability purposes"] instead.
  • leave the inline filter pointing to images (screenshots) in place for the moment until we sorted out a good uniform standard.

Images are not copied over from the 1.x handbook to the 2.0 placeholder. You will still find the inline filter in the copied text as a reference to the image. The goal is to create new screenshots and attach them to the pages. We will have to decide first how to standardise the screenshots.

If you have questions, please leave a comment.


Comments

When I try to edit the current handbook (for MuseScore 1.3), I have this error: "An illegal choice has been detected. Please contact the site administrator."

The input format selected by default is "Filtered HTML". Must I select the input format "Handbook" and convert the content to Markdown?

In reply to by jpfle

The error you is caused bc the token of the form did not match with what the site expected. It's a security measurement against XSS. There are various reasons why this may have happened to you. Once is that you logged out and back in via another browser window.

Let's freeze the state of the 1.3 handbook and concentrate on the 2.0 handbook. So I advise not to work anymore on the 1.3 handbook.

In reply to by Thomas

Thanks for the comment. Actually, I was thinking more about when using Markdown for an issue or a comment.

By the way, is it normal that Markdown can be used to comment an issue but not a forum topic?

Almost all pages have been converted to markdown now, only exception is the glossary (I started converting it).
This and a few other pages use definition list and I haven't yet found a good markdown replacement for that
Similar issue with a few pages that use tables. As per the documentation you linked to tables should work, as plain HTML, but is seems Drupal doesn't like them, they render pretty bad, check "figured bass" for example.

Any ideas/hints how to convert definition lists and tables?

Some Markdown properties don't work (I suppose it's because there's a filter to sanitize HTML applied before the Markdown filter):

  • URL between brackets:
    <URL>

    Workaround:

    [URL](URL)
  • Blockquote:
    > Text
    > Text
    > Text
    
  • Automatic encoding of HTML entities in code, either inline:
    `<tag>content</tag>`

    or with indentation:

        <tag>content</tag>
    

    Tags are stripped before the Markdown filter sanitize them, so the HTML result is:

    <code>content</code>

In reply to by Jojo-Schmitz

If you want to add an "id class" attribute to elements that are not supported by Markdown Extra, here's an easy workaround:

Say you have this definition list in Markdown:

Word 1
: definition

Word 2
: definition

Word 3
: definition

and you want to add an "id class" attribute to the second word. You can add an empty link with an "id class" attribute:

Word 1
: definition

Word 2[](){#word2}
: definition

Word 3
: definition

Then you can link directly to this word by using:

See [word 2](#word2).

One issue I'd like to see a solution for is making thinks like
[node:<id>#<marker>,title="<text>"]
work, the #marker part.
The syntax itself works, but it doesn't jump to the marker on the target page.
And the alternative
[<text>](/en/node/<id>#<marker>)
is to cumbersome IMHO (but jumps to the right spot)

Another question is whether and how to integrate HowTos, Tutorials and FAQs into the handbook.
Doing it should result in getting translated version too, which I'd regard a very good thing

Do you still have an unanswered question? Please log in first to post your question.