Hi Kees, Em Mon, 16 Sep 2019 20:35:45 -0700 Kees Cook <keescook@xxxxxxxxxxxx> escreveu: > On Fri, Sep 13, 2019 at 01:19:21PM -0300, Mauro Carvalho Chehab wrote: > > Document the basic policies of the media subsystem profile. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> > > --- > > > > That's basically a modified version of: > > https://patchwork.linuxtv.org/patch/52999/ > > > > Applied to the new template > > > > Documentation/media/index.rst | 1 + > > .../media/maintainer-entry-profile.rst | 140 ++++++++++++++++++ > > One idea I proposed to Dan at the Maintainer's Summit was to collect all > the profiles is a single directory in Documentation/, 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. 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. > 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. Thanks, Mauro
