Edit Markup

    From KDE UserBase Wiki
    Revision as of 13:46, 9 July 2010 by Hans (talk | contribs) (→‎Combined Bold and Italics: Also make "user" bold (and italic))

    Preparing a Page for Translation

    Available Tools

    • Typographical_Guidelines standardises markup for use in translation, either to official manuals (DocBook) or to other languages. Please refer to this frequently, as markup will be refined to match translators' needs.

    Workflow Stage 1

    Correcting old markup

    • Check that every heading for sections and subsections has an empty line following it.
    • Many pages have multiple indents set. This was included in earlier mediawiki documentation, but is not longer acceptable as it causes problems for exporting to other formats, so please re-arrange, using single indents only. Bullets can continue to be used nested.
    • Ascii smilies cause problems and must be removed. They can be replaced by oxygen icons in a small size (11px?). Many more are available from Wikimedia Commons - details to be added here.
    • Internal links in the form [[Translation Workflow]] should be edited to the complete form, showing link, then visible text such as [[Translation_Workflow|Translation Workflow]]
    • Many styles have been used to display input text, including <code>, <pre> and tables and boxes. Text intended to be input by the user should use the Input template, {{Input|1=input text (can be multi-line or single)}}
    • Output from terminal and error messages have been similarly marked with a variety of methods. These should be replaced with the Output template, {{Output|1=terminal output}}
    • Every page should end with a Category statement. These must be standardised categories. A current list of categories can be found on any of the translators' pages linked from this language page

    Stage 2 - Guide to new markup

    Special Tags

    • Identify all keyboard key-names, and tag, e.g. <keycap>Enter</keycap>
    • Include concurrent keypresses in the <keycap> tag, e.g. Ctrl + Alt + F1 (note that the separator is "+")
    • Treat menu sequences in a similar manner, using the <menuchoice> tag, e.g.System Settings -> Account Details -> Social Desktop. Note that the separator is (space)->(space).

    Bold type

    • Identify program names and mark them as bold type, e.g. '''klipper'''
    • Identify labels and names that cannot be changed by the user, and mark them as bold type.
    • Remove any bold type marking that were previously entered, but do not match this guideline. (See below for emphasising a word or phrase.)
    • Window captions and Icon labels are also marked as bold type.

    Italics

    • Italics can be used to give emphasis as you might in non-technical writing
    • Use italics on the first appearance of an unfammiliar word or phrase, and if possible link it to #Glossary or a dictionary entry.
    • When referencing other (external) works, titles are italicised.

    Combined Bold and Italics

    • This should only be used in the context of an example where the user has to substitute text, e.g. "Your new addressbook records are in /home/user/share/contacts"
    Tip
    Simplified definitions - Programs are launched by users, components are used by programs

    Almost finished

    • In the summary field at the bottom, enter that you are doing a markup edit.
    • Use Preview and read through the whole of your work. If you are satisfied, save the page.
    • Use the link in the sidebar to request release - it takes you to a page where you can add the URL of the page you have edited. Pasting your link there tells us that you believe the page to be ready for translators to work with. We will scan it, and if satisfied we will enable it for translation.