Rendering of README.md inline with inner tree view dirs

[john at keeping.me.uk (John Keeping)]

On Wed, Jun 13, 2018 at 09:47:38AM +0800, Andy Green wrote:
> 
> 
> On 06/12/2018 05:31 PM, John Keeping wrote:
> > On Tue, Jun 12, 2018 at 01:53:27PM +0800, Andy Green wrote:
> >> On 06/11/2018 11:38 PM, John Keeping wrote:
> >>> On Mon, Jun 11, 2018 at 04:05:38PM +0800, Andy Green wrote:
> 
> >> 1) I did not attempt to have it learn about suitable filenames from the
> >> config yet, I just have ls_item() looking for "README.md".  I saw
> >> there's already a way (readme=) for the config to list them for the
> >> about page... basically now tree view becomes a superset of the
> >> operation of the about page; the about page content appears in tree view.
> >>
> >> So do you have any thoughts about just re-using that list?
> > 
> > I think that list is refs to blobs, so you can specify something like:
> > 
> > 	refs/heads/wiki:README.md
> > 
> > but here we need base filenames to look for in the current directory, so
> > it will have to be a new config variable.
> 
> OK.  I added a new cgit-scope variable that appends filenames to be 
> considered for showing in tree view, eg,
> 
> tree-readme=README.md

This should be overridable at the repo level to match our other
configuration variables which affect this sort of behaviour.

Also, if this was my bikeshed I'd paint it as "inline-readme", but I
don't feel strongly about that.

> >> 2) In the current patches, I allowed for ls_item to discover a
> >> linked-list of files and render them later one after the other.  Eg, a
> >> dir of READMEs would render them like that.  It's welcome or preferable
> >> to just restrict it to one?
> > 
> > My choice would be to take the first matching file, but I don't have a
> > strong opinion on what is the right behaviour.
> 
> I'll leave this as a list for the first try.  If it looks excessive I'll 
> reduce it to just the one.

The code is definitely simpler if it's just one, and I'm not sure what
benefit we get from including multiple files.  But if you have a use
case for multiple readme files, then a list is okay.

> >> 3) You can see on the top level of the tree, the README.md references
> >>
> >> <img alt="lws-overview" src="./doc-assets/lws-overview.png">
> >>
> >> This url format works in github.  In the cgit About view, this resolves to
> >>
> >> /git/libwebsockets/about/doc-assets/lws-overview.png
> >>
> >> which also serves the right mimetype and content.  So that kind of URL
> >> format is useful.  But when we render the same markup and relative path
> >> via /tree/, it tries to show an html page containing the content.
> >> That's why the picture is missing in the /tree/ view... other pictures
> >> in that markup are coming with absolute URLs outside of cgit and are
> >> working.
> >>
> >> I can have the direct content from cgit generally, but either the markup
> >> needs fixing up to
> >>
> >> /git/libwebsockets/plain/doc-assets/lws-overview.png
> >>
> >> or /tree/ needs to learn to do what /about/ does.
> >>
> >> I'm wondering whether mmd2html might grow an environment var to know the
> >> base part for URLS that want to direct-render from cgit.  Or if better
> >> to follow what /about/ did in /tree/.
> > 
> > Making tree do this will break the normal use of tree unless we add some
> > extra query parameter or path element.  Given that, I think teaching the
> > renderer to use a path to /about/ is the right thing to do.
> 
> OK.  Unfortunately I don't know python very well.  It looks like the 
> markdown python library is able to be told to use extensions that are 
> capable to do this
> 
> https://python-markdown.github.io/extensions/api/
> 
> from the md2html wrapper.  But I don't know enough python to do it.
> 
> It's a shame, because in-tree assets correctly follow the ref context 
> being viewed, eg, if you look at a v2 branch you see v2 pngs, master you 
> see master pngs etc.
> 
> I'll "solve" this part for now by changing the README to use external URLs.

Yeah, I think we have to solve it by having the filter apply a mapping.
We have ui-plain which provides the right content for images, but what
should we do for link targets?

For the purpose of discussion, consider the following HTML fragment that
could be generated by rendering a README file:

	<img src="dataflow.png">
	<p>For more details see <a href="dataflow.html">the dedicated
	data flow document.</p>

If dataflow.html is generated from a source file in a similar way, then
it doesn't exist in the repository and we can't link to it, so the ideal
output ends up being something like:

	<img src="/repo/plain/dataflow.png">
	<p>For more details see <a href="dataflow.txt">the dedicated
	data flow document.</p>

The render filter API isn't finalised yet, so we can change the
parameters that are passed in order to add more information for the
renderer to use.  At the very least I think we should add a parameter
for the asset prefix which is essentially the tree path with /tree/
replaces with /plain/.

However, I'm not sure how to handle relative links: do we need to pass
additional parameters for this?  Or can we rely on a render filter doing
the right thing?


Regards,
John