From mboxrd@z Thu Jan 1 00:00:00 1970 From: john at keeping.me.uk (John Keeping) Date: Mon, 11 Jun 2018 16:38:58 +0100 Subject: Rendering of README.md inline with inner tree view dirs In-Reply-To: References: <20180611093152.4821159f@leda> <20180611095343.2865c71d@leda> Message-ID: <20180611153858.GJ1922@john.keeping.me.uk> 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 on Mon, 2018/06/11 15:38: > >> On 06/11/2018 03:31 PM, Christian Hesse wrote: > >>> Andy Green 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 > 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 > > Author: John Keeping > Date: Wed Dec 14 20:35:47 2016 +0800 > > ui-tree: split out buffer printing > > Signed-off-by: John Keeping > > Author: John Keeping > 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 > > Author: John Keeping > 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 > > Author: John Keeping > 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 > > 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