On Tue, Sep 17, 2019 at 10:28:17AM -0300, Mauro Carvalho Chehab wrote:
> No matter where the profiles will physically be stored, its contents belong
> to subsystem-specific documentation, and should be visible at the same index
> file as the kAPI docs is located, as anyone interested on submitting patches
> for a subsystem should be aware about the subsystem specific policies and
> details.
That's a good point. I think your other suggestions below address my
"find them all" case...
> So, my vote is to store them at Documentation/*/<subsystem> (together
> with the kAPI book).
>
> > since there are
> > two ways someone would want to read profiles:
> >
> > 1) a single profile, based on a MAINTAINERS entry which includes the path
>
> That is the common case. The problem is that the MAINTAINERS file
> currently doesn't generate html output. This is not a problem for
> "old school" devs, but a newbie wanting to collaborate to a single
> specific subsystem may not notice - or understand - the importance
> of the MAINTAINERS file[1].
>
> [1] btw, that's why I submitted a RFC, several years ago, a patch
> converting it to ReST - and later - another patch that would be parsing
> its contents and producing a ReST output.
>
> That's, by far, the most relevant usecase for the profiles, as the
> audience is the ~4k Kernel developers.
Oh yes, having a .rst of the MAINTAINERS file would be pretty great.
Seems like it could just be a build target (and then dependency) for the
sphinx targets?
> > 2) all of them, to study for various reasons
>
> I suspect that only core people will have interest on study them.
>
> Those people are more skilled, and can easily find all those files with
> a simple grep:
>
> $ grep "^P:\s" MAINTAINERS|cut -d':' -f2-
>
> or
>
> $ git grep "^P:\s" MAINTAINERS|cut -d: -f3-
>
> If, for whatever reason, he would prefer an HTML output [1], he could even
> create an index file with all of those with something like:
>
> $ for i in $(grep "^P:\s" MAINTAINERS|cut -d':' -f2-); do j=${i/rst/html}; echo "<a href=\"$j\">$j</a><br/>"; done >Documentation/output/index_profiles.html
>
> We might, instead, teach the Documentation/Makefile to create something
> like the above, but, IMHO, that would just add more complexity to the
> build without a good reason.
>
> [1] I doubt that core devs would prefer seeing this in html form, but some
> variant of the above could be used, for example, to create symlinks for
> all profile docs into a "study" directory.
>
> > The #2 case is helped by having them all in one directory with a single
> > index.rst, etc. Then similar profiles are able to merge, etc.
Whatever the case, please don't let me distract from the actual content
of these profiles: I think it's awesome to capture these details and
makes my life so much easier. :)
--
Kees Cook
