Rendering of README.md inline with inner tree view dirs

[andy at warmcat.com (Andy Green)]

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.

-Andy