Allow richer styling of questions/answers

[Daniel Holbach]

Our workflow is quite special, we use
 - po4a for extracting strings for translation from markdown files
 - Launchpad to get translated .po files
 - po4a again to produce translated markdown files
 - pelican to produce HTML from those markdown files

Everything is glued together in translations.py.

To allow richer styling (think of it as Q&A classes, ie: "short", "long", "with picture", etc.) we will need to specify this in the markdown somewhere, make sure it doesn't get broken through translations, then use some mechanism to inject styling into the resulting HTML.

The current plan for this is:

 - use some kind of special markdown to indicate what kind of question and answer we have
 - save it in a .pot comment
 - massage translations into markdown, re-add styling markers
 - maybe use a markdown extension for generating the html we need(?)

Current work items:
 - David: figure out individual theming bits
 - Daniel: investigate options wrt. pot comments and markdown extensions

Here is some info about creating a Pelican plugin: http://nafiulis.me/making-a-static-blog-with-pelican.html

[David Planella (dpm)]

I think markup that could work for at least the web theme would be:

For text-only questions:

<div class="row">
  <div class="eight-col last-col">
     <!-- question & answer -->
  </div>
</div>

For text and picture questions:

<div class="row">
  <div class="eight-col">
     <!-- question & answer -->
  </div>
  <div class="four-col last-col">
     <!-- question & answer -->
  </div>
</div>

An option that would work would be to add that additional markup to the .md files. However, that makes them more difficult to edit, and we'd have to remove the markup from the .pot file and re-add it to the translated .md files, which might prove to be too complex.

[David Planella (dpm)]

Apart from raw HTML markup, another option to have more control over the layout is to add class information to the original sources, which will be translated into HTML markup by Pelican. This can be done via python-markdown extensions, in particular via attribute lists [1] (which are enabled by default in Pelican).

As an example, if I add the following to index.md:

# Header 1 {: .myclass}

Pelican will create this markup in index.html

<h1 class="myclass">Header 1</h1>

This has the challenge that {: .myclass} will be put into the .pot file too. Daniel devised a plan to move it to the translator comments and then put it back in the index.$LANG.md files too, which could work well.

However, while attribute lists give us more control over CSS classes, I'm not sure we've got a definite use case for using them yet.

[1] https://pythonhosted.org/Markdown/extensions/attr_list.html

[Daniel Holbach (dholbach)]

lp:~dholbach/help-app/1430735 is my work-in-progress. It's based on lp:~dpm/help-app/attr-lists-and-embedded-html

[Daniel Holbach (dholbach)]

<dholbach> dpm, so... to implement this, I think it'd make sense to always assume something like ".textonly"
 as it's likely going to be the primary way how we present questions and answers
 so for cases where we add a picture, we could add something like ".image"
 or ".highlight" in case we ever want to do that
 and add the statement to both question and answer line
 so the extension knows what to do and what to replace it with
 does that generally make sense?
<dpm> right, yeah. But perhaps we'd need to use some other notation to distinguish it from the python-markdown attribute lists
 what I mean is that we use {: .someclass} to add a class to an element
<dholbach> dpm, I was actually thinking of dropping the attr-list extension again
<dpm> but with this new extension we'd be wrapping divs around the questions
<dholbach> as we don't necessarily use it right now
<dpm> dholbach, sounds good to me if we're not using it, yeah
* dholbach nods

[Daniel Holbach (dholbach)]

!!I we are going to postpone to 0.2 - this is bug 1432710.