[Ohrrpgce] Help page markup

[Ralph Versteegen]

On 19 June 2017 at 03:22, Ralph Versteegen <teeemcee at gmail.com> wrote:

>
>
> On 19 June 2017 at 03:09, Ralph Versteegen <teeemcee at gmail.com> wrote:
>
>> Currently we have some problems with F1 help pages which use indentation
>> not being resolution-independent. (Example attachment)
>> There actually already is a text markup code, ${LM#} (which I will rename
>> at some point), to add a left margin (ie left indentation) to the current
>> paragraph of text. But it's awkward to use. And besides, I want other
>> things, like headings and web links and cross-links.
>>
>> A moment's thought indicates that we should write help pages in a
>> separate markup language (which goes beyond the markup codes to change font
>> colour and so forth). Preferably an existing one. And there's an obvious
>> choice: mediawiki markup. That will allow moving content between the wiki
>> and the engine in both directions easily, make it easy for anyone who's
>> learnt to edit the wiki to edit the help pages, and makes it easy to link
>> back and forth between the wiki and the help pages.
>>
>> We would be implementing a subset of mediawiki markup in FB, translating
>> to "native" markup codes understood by render_text plus metadata needed to
>> search for clickable links. (As you can see in the Spam menu, translating
>> pixel posiiton to character number is currently broken)
>>
>> -* bullet points
>> -: indentation
>> -==Multiple heading levels==
>> -[[internal links]]
>> -[external links]
>> -{{plot|script command links}}
>> -bold, italic, and pre
>> - horizontal lines ----
>> -Newlines are ignored, so that existing help pages largely automatically
>> become resolution independent
>>
>> Also, adding support to render_text for drawing inline images (without
>> using slices) would be really easy. Even floating images could be
>> straigthforward, since it's similar to the existing ${LM#} and ${RM#} codes.
>>
>> We could translate help pages to static HTML, host them online, and link
>> to them from the wiki. (From previous experience, having two editable
>> copies would be a nuisance.) I wonder, is it possible to have a special
>> namespace on the wiki which auto-redirects links link [[F1:attack bitsets]]
>> to some external html pages? (Or we could write a plugin for the wiki which
>> fetches the content of page from a file so that it's rendered like a normal
>> wiki page; that looks quite feasible.) Alternatively, we can just use a
>> template, like {{help|attack bitsets}}. And the engine can use the same
>> syntax for links to other help pages, and use links styled like [[Attacks]]
>> to link to the wiki, so that the syntax is identical everywhere!
>>
>>
> Oh, and I imagine there would be two types of templates supported, both
> using {{this syntax}}.
> Real (but probably argument-less) templates (page transclusion) would be
> useful. We have lots of pages with repeated content (which I'd like to
> replace with links to central pages, like "[[Standard menu controls]] work
> here.", but even that line could be added by a template.
>
> We would also have special templates hardcoded in FB, such as {{plot}}
> which I mentioned, and probably some others. Eg. why not use semantic
> markup such as {{key|space}}, {{key|ctrl+R}}? Then we could process the
> help page to produce a concise list of all keyboard shortcuts (displayed
> with a special hotkey!) At worst, these would just link to the right
> location in the help page, but the meaning of that key could obviously be a
> description of it.
>
Err, I mean, a short description of the key could be an argument to the
template.
Also, once you have a list of keys that a used in a menu, and their
descriptions, it's even feasible to add a way to remap the controls used in
that menu!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.motherhamster.org/pipermail/ohrrpgce-motherhamster.org/attachments/20170619/59da4e0b/attachment.htm>