[PATCH v4 00/16] Render READMEs inline in tree view

[Andy Green]

On 06/28/2018 01:18 AM, Jason A. Donenfeld wrote:
> Hey Andy,
> 
> Thanks for this patchset. It looks like this is shaping up into a nice
> direction. However, I'm a bit concerned about our nobs becoming
> slightly overlapping and incoherent, and I think that with this
> series, we should also unify how we handle rendering.

Well, I can understand that from your POV.

However I also have a POV... "This series" represents my attempt to 
align cgit to a piece of github that my users will definitely miss. 
Nobody is paying me to do it and I don't have an endless budget of time 
to lavish on it (and it seems, neither do you...).

If cgit can't do what I need in a reasonable timescale, even with my 
contribution, my choices are:

  - become a cgit developer until the happy day comes

  - maintaining my own OOT branch until it can natively do the same thing

  - use something else

> With the current state of this series, cgit would have the following options:
> 
> - render.<ext>
> - inline-readme
> - render-filter
> - about-filter
> - commit-filter
> - source-filter
> - owner-filter
> - readme=file
> - readme=:file
> 
> Whoa nelly. Of these, about-filter, commit-filter, source-filter, and
> owner-filter all have analogs in the repo.* namespace, which makes
> sense; it seems this was omitted from the render-filter introduced by
> this series. The thing that unifies about-filter, commit-filter,
> source-filter, and owner-filter is that they all modify some aspect of
> the rendered output, either via fork/exec or via lua.
> 
> In adding readme files under the tree view, the obvious observation is
> that this is pretty much the same type of rendering that we're doing
> in about-filter.

Yeah, about has lost all meaning if this series gets in.

> In adding rendering of arbitrary files in blob view, this is
> essentially a fancy source view, with the one caveat of our
> interesting handling of line numbers.
> 
> So, I'd propose the following re-organization (and after we nail it
> down, we can bikeshed about compatibility with old configs, but for
> now let's focus on ideal design):
> 
> - We retain commit-filter, source-filter, and owner-filter as we have them now.
> - We rename about-filter to readme-filter.
> - We remove `readme` and instead introduce `readme-filename`, which
> can be specified multiple times as is habit. This would simply take
> the set of filenames considered to be readme files (readme.md,
> readme.txt, etc). [Bikeshed discussion: case insensitive?]

... what's actually wrong with aligning with The Github Way?

> - We introduce an options at the global level and at the .repo level
> of `about-readme=/path/to/absolute/file` and `about-readme=<BRANCH> > and `about-readme=:`. The first would replace our original usage of

How "about" just drop about-*, and the about tab, ui-about-* etc.

Set the readme names using both [repo.]about-readme= for compatibility 
and [repo.]readme=

Almost all projects have a README of some kind at the root of their 
source tree.  It was a standard layout for decades.  So this just 
replaces about.  And aligns with github.

> `readme=/path/to=file`, and the second would replace the use of
> `readme=branch:whatever`, specifying an explicit branch (like
> cgit.git's wiki branch), and the third would indicate the default
> branch.

... and don't do that, just show the inline README for the rev context.

> - We introduce an option at the global level and at the .repo level of
> `tree-readme=1/0` to display (or not) the readme under each tree.

... just always display any compatible readme a la github.

> - We do not introduce render-filter. We do not introduce render.<ext>;
> such extension selection is successfully handled by the various
> filters themselves already.

That I don't know much about.  However, we can at least get rid of or 
repurpose about filter for this, if about if going away.

The copyright message says cgit has been around 22 years... since then 
programmers have been born and since the age of 12 their view of git has 
been shaped only by github.  It's not that hard to overstate its 
importance but in a few ways, unless something in cgit is really better, 
the way forward is to align, or align and improve... IMHO.

-Andy

> John, Christian -- what are your thoughts on this?
> 
> Regards,
> Jason
>