Handbook 2.0 collaboration
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
For the first step we are converting the html in the handbook pages listed at http://musescore.org/en/node/35711 to the Markdown syntax. Step 2 will be about working on the actual content. We'll comment on here when step 1 is finished.
If you like to join this effort, please reach out to us on IRC at #musescore on freenode.net.
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 When I try to edit the 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.
It seems that the following filter doesn't work with the input format Markdown: "Github commits (eg abc1234) turn into links automatically."
In reply to Github commits filter by jpfle
I pushed down the number of input filters for the handbook. In particular, hyperlinking to Github commits should not be part of the handbook.
In reply to It's not supposed 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?
In reply to Almost all pages have been by Jojo-Schmitz
@Jojo-Schmitz: theoretically, we can use plain HTML with Markdown, but I think there's a filter on the Drupal site that sanitizes HTML tags, so we must use the Markdown syntax:
In reply to @Jojo-Schmitz: theoretically, by jpfle
Yes, found that myself meanwhile.
What I'm missing is internal links, from one definition to another, {#jumptarget} like for headers doesn't seem to work
Some Markdown properties don't work (I suppose it's because there's a filter to sanitize HTML applied before the Markdown filter):
Workaround:
or with indentation:
<tag>content</tag>Tags are stripped before the Markdown filter sanitize them, so the HTML result is:
In reply to Some Markdown properties by jpfle
Indeed, the site strips away all html tags except for kbd and samp. If there is a good reason to allow other elements, I will add them to the whitelist. I'll check for the blockquote formating though.
In reply to Allowing tags by Thomas
what about <div id=something>...</div>
Could use it in the glossary
In reply to what about <div by Jojo-Schmitz
Can we find a more creative solution with Markdown? Or perhaps use a different formatting for the glossary? I want to prevent use of HTML as much as possible.
In reply to Something different? by Thomas
Somehow enable the {#marker} syntax?
In reply to Somehow enable the {#marker} by Jojo-Schmitz
Markdown Extra doesn't support adding id class attributes everywhere. For a list of elements supported, see //michelf.ca/projects/php-markdown/extra/#spe-attr
In reply to Somehow enable the {#marker} 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:
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 : definitionThen you can link directly to this word by using:
In reply to If you want to add an "id by jpfle
Cool, that indeed works
Check what I did to the Glossary
In reply to Some Markdown properties by jpfle
<code>content<code> could get rewritten as <samp>content<samp> or maybe <samp class="code">content<samp>
In reply to <code>content<code> could get by Jojo-Schmitz
Where would you need the code element?
In reply to code by Thomas
I've eliminated it meanwhile, see http://musescore.org/en/node/35956
It was used there earlier http://musescore.org/en/node/35956/revisions/59181/view
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)
In reply to One issue I'd like to see a by Jojo-Schmitz
Ok, let me look into it. It will require some code changes so give me some time.
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
In reply to Another question is whether by Jojo-Schmitz
Each one of these content types (book, howto, tutorial, faq) serve a different goal so integration is not under discussion.
We can place the translation system under scrutiny once the update for the handbook 2.0 has been completed.
Can you please check http://musescore.org/en/node/36096, the 1st Heading doesn't render properly
In reply to Can you please check by Jojo-Schmitz
Navigation as id is already used in the site design framework, so basically a reserved identifier.
In reply to Navigation by Thomas
Ah! Thanks!
There seems to be no equivalent for <u>text</u> in Markdown, i.e. mark something as underlined.
Needed in http://musescore.org/en/node/35996