source/render plain text file to html

[Fathi Boudra]

On releases/snapshots.linaro.org [1], we use HEADER.html file to include documentation.
We would like to reuse the plain text file(s) [2] to avoid to write a copy in HEADER.html.
In addition, the plain text file(s) will be soon generated as a build artifact by the build system.

The idea is that we can have several files to source (e.g. INSTALL README GETSOURCE HACKING)
and we would like to be able to include a <%source INSTALL%> in HEADER.html file to source/render it.

You'll find attached an example of such HEADER.html/README files, using the new %source% annotation.

[1] http://releases.linaro.org/12.06/ubuntu/vexpress/HEADER.html
[2] http://releases.linaro.org/12.06/ubuntu/vexpress/README

[Fathi Boudra (fboudra)]

Anmar suggested to look at the markup add-on for django:
http://www.freewisdom.org/projects/python-markdown/Django

[Данило Шеган (danilo)]

At this time, we have agreed to include a simple tag to "source" other files present in the same directory as the HEADER.html.

Eg. it should support something like

  <linaro:include file="README" />

and simply replace the contents of the file README in that spot of HTML. If the file doesn't exist, simply put an empty string in.

We should make sure one can't do "../README" or get files from a subdirectory: that's a potential security risk.

[Alexander Sack (asac)]

To set expectations about what level of work investment is assumed from Infrastructure to complete the first stage as descibed by danilo, here very rough numbers pointing in the right direction:

 * 2 engineering work days worth of total development and discussion (one day for initial code and 1 day spread over a few days to do iterations)
 * 1 day of total engineering cycles spend on IS coordination (spread over a couple days <4) - this is somehting that can be handled as a secondary task as IS communication through RT tickets is by average far from a real time interaction experience.

If you think about potential solutions that are too hard to do in such a timeframe, but you still feel it is worth doing, please let me know asap for further consideration. Also, let me know as soon as there are roadblocks that risk the delivery.

Thanks!

[Georgy Redkozubov (gesha)]

Initial implementation of including plain text file in HEADER.html is live on both snapshots.l.o and releases.l.o. It allows to include files that are located in the same directory as HEADER.html. Following tags are supported:
<linaro:include file="README" />
<linaro:include file="INSTALL"></linaro:include>

'file' property contains file name with data to be sourced.

[Fathi Boudra (fboudra)]

Verified on releases.linaro.org. Mark as fix-released. Thanks.