Rendering of README.md inline with inner tree view dirs

[John Keeping]

On Mon, Jun 11, 2018 at 04:05:38PM +0800, Andy Green wrote:
> 
> 
> On 06/11/2018 03:53 PM, Christian Hesse wrote:
> > Andy Green <andy at warmcat.com> on Mon, 2018/06/11 15:38:
> >> On 06/11/2018 03:31 PM, Christian Hesse wrote:
> >>> Andy Green <andy at warmcat.com> on Mon, 2018/06/11 15:08:
> >>>> Hi -
> >>>>
> >>>> I have been using cgit for many years.
> >>>>
> >>>> Currently I am detaching my (LGPL) project from github.
> >>>>
> >>>> One noticeable problem diverting people from github to cgit is although
> >>>> it renders very well the toplevel "about" README.md
> >>>>
> >>>> https://libwebsockets.org/git/libwebsockets/about/
> >>>>
> >>>> It doesn't seem to have a way to render inline inner dir README.md as
> >>>> github does.  This is quite a small thing but very useful, eg
> >>>>
> >>>> https://github.com/warmcat/libwebsockets/tree/master/minimal-examples
> >>>>
> >>>> vs
> >>>>
> >>>> https://libwebsockets.org/git/libwebsockets/tree/minimal-examples
> >>>>
> >>>> Is there a way to do it already in the main cgit project?  For nonpublic
> >>>> projects, I screenscraped some patches from John Keeping from 2016 that
> >>>> do the same thing, but poking around, these don't seem to have made it
> >>>> in.
> >>>>
> >>>> If there's no existing way to do it and those patches are shivering in
> >>>> the cold, all alone, can I suggest they would perhaps be extremely
> >>>> useful to people in a similar position, needing to decouple users from
> >>>> github but needing to generally present the same tree in a similar way?
> >>>
> >>> This is what you want?
> >>>
> >>> https://libwebsockets.org/git/libwebsockets/about/minimal-examples/README.md
> >>
> >> Yeah.
> >>
> >> But inline after the tree view, a la github.
> >>
> >> This enables a scheme where inner dirs give their own overview without
> >> interrupting navigation.  Eg, a couple of levels down...
> >>
> >> https://github.com/warmcat/libwebsockets/tree/master/lib/roles
> > 
> > I think this is not possible with current code. What patches from John did
> > you apply?
> 
> 
> Author: John Keeping <john at keeping.me.uk>
> Date:   Wed Dec 14 20:35:47 2016 +0800
> 
>      Use string list strdup_strings for mimetypes
> 
>      This allows applying filters to files in the repository, for example to
>      render Markdown or AsciiDoc as HTML.
> 
>      Signed-off-by: John Keeping <john at keeping.me.uk>
> 
> Author: John Keeping <john at keeping.me.uk>
> Date:   Wed Dec 14 20:35:47 2016 +0800
> 
>      ui-tree: split out buffer printing
> 
>      Signed-off-by: John Keeping <john at keeping.me.uk>
> 
> Author: John Keeping <john at keeping.me.uk>
> Date:   Wed Dec 14 20:41:11 2016 +0800
> 
>      Parse render filters from the config
> 
>      Render filters will be used to present rendered content in the tree
>      view, for example to display Markdown source rendered as HTML.
> 
>      We will add support for using these from the tree view in the following
>      commits.
> 
>      Signed-off-by: John Keeping <john at keeping.me.uk>
> 
> Author: John Keeping <john at keeping.me.uk>
> Date:   Wed Dec 14 20:36:51 2016 +0800
> 
>      Add source page
> 
>      We are about to introduce rendering of content for the tree view.  This
>      source page will allow bypassing the renderer and accessing the content
>      of the current tree view.
> 
>      Signed-off-by: John Keeping <john at keeping.me.uk>
> 
> Author: John Keeping <john at keeping.me.uk>
> Date:   Wed Dec 14 20:35:47 2016 +0800
> 
>      Use string list strdup_strings for mimetypes
> 
>      There's no need to do this manually with the string list API will do it
>      for us.
> 
>      Signed-off-by: John Keeping <john at keeping.me.uk>
> 
> It's quite possible they aren't what I am asking for, and / or already 
> applied.  They were "good enough" for what I needed to do a couple of 
> years ago.  But now I am explicitly replacing github, so comparing the 
> rendering is in scope for me when it just needed to be able to render 
> anything at all back then.
> 
> > BTW, linking withing formatted pages works, so this could be a step forward:
> > 
> > diff --git a/README.md b/README.md
> > index c6222b75..fee7dcae 100644
> > --- a/README.md
> > +++ b/README.md
> > @@ -9,7 +9,7 @@ News
> >   
> >   ## v3.0.0 released
> >   
> > -See the changelog for info https://libwebsockets.org/git/libwebsockets/tree/changelog?h=v3.0-stable
> > +See the [changelog](changelog?h=v3.0-stable) for info.
> >   
> >   ## Major CI improvements for QA
> >   
> > @@ -56,7 +56,7 @@ but the other browsers will catch up soon.
> >   
> >   ## New "minimal examples"
> >   
> > -https://libwebsockets.org/git/libwebsockets/tree/minimal-examples
> > +[minimal-examples](minimal-examples/README.md)
> >   
> >   These are like the test apps, but focus on doing one thing, the best way, with the minimum amount of code.  For example the minimal-http-server serves the cwd on http/1 or http/2 in 50 LOC.  Same thing with tls is just three more lines.
> > 
> 
> I think what github did comes into its own when you are in the mode of 
> coming new to a project and trying to understand what you are even 
> looking at from the project layout in the filespace.  So they may well 
> be clicking around in the tree view, it's perfect if any project 
> documentation in that dir just magically appears after the already 
> expected navigation context explaining it.
> 
> Basically any available docs follow along contextually.
> 
> I think it's desirable under all circumstances, since it's only coming 
> if someone bothered to put relevant docs right there... if no way to do 
> it right now and no better ideas, I will try to understand how cgit 
> works for this tomorrow and see if any ideas.

I think this is a potentially useful feature; long before GitHub existed
web interfaces to file servers have included README content with the
directory listing.

Given the render mode patches you listed above, I think it should be
reasonably straightforward to add this feature in ui-tree.c with the
following changes:

- Add fields to walk_tree_context to remember the filename and object_id
  of a target README file (this needs some configuration to answer the
  question: what is a README file?) and populate these during the normal
  tree walk (probably in ls_item(), being careful to only accept blobs)
- In ls_tail(), if the walk_tree_context has valid values for those
  fields, then read the blob content from the object_id and call
  render_buffer()

This will re-use the existing render filter for "inline" README content,
which I think is a good thing.  I think the filenames for READMEs will
have to be a new configuration (the existing "readme" configuration
takes a blob ref whereas this option wants a simple filename).


John