[Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues

[Daniel Vetter]

On Mon, Jun 26, 2017 at 11:28 PM, Rafael J. Wysocki <rjw at rjwysocki.net> wrote:
> On Monday, June 26, 2017 07:58:27 AM Takashi Iwai wrote:
>> On Sun, 25 Jun 2017 22:56:07 +0200,
>> Jiri Kosina wrote:
>> >
>> > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote:
>> >
>> > > > There are pieces of .txt documentation falling into the "well-knows source of
>> > > > information" category, with many references to them all over the Web.
>> > > > kernel-parameters.txt is probably the most spectacular example here, but there
>> > > > are others.
>> > > >
>> > > > Let us not move or rename these, please, or at least put symbolic links in
>> > > > place to point to the new locations or similar, such that the existing WWW
>> > > > links pointing to the documentation at kernel.org still work going forward.
>> > > >
>> > > > And if we have moved or renamed them already, can we possibly make these
>> > > > links work again somehow?
>> > >
>> > > Agreed. We discussed in the past about two alternatives for those
>> > > "well known" documents:
>> > >
>> > >   1) write a small text on the old file pointing to the
>> > >      new location;
>> > >   2) use symlink.
>> > >
>> > > Right now, we're actually mixing (1) and (2). IMHO, we should either
>> > > do (1) or (2).
>> >
>> > Unfortunately option (3) has also been applied to some of the files:
>> >
>> >     $ ll Documentation/kernel-parameters.txt
>> >     ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory
>> >
>> > I wasn't sure whether this was intentional or not. But if not, I'll
>> > happily send a patch that introduces a symlink.
>>
>> If we do symlinks, wouldn't it be cleaner to separate the old doc
>> directory from the new doc directory?  That is, Documentation/* keeps
>> the old txt or symlinks while the ReST is put in another directory,
>> say, docs/* as originally suggested.
>
> That actually sounds like a good idea to me. :-)
>
> Question is if it's not too late to do that now that we have all that stuff
> under Documentation/.

I think it's a bit late, at least from more documentation-active
susbsystems like gpu/. The docbook->rst switch was pains, dealing once
more with piles of renames isn't really something I'd like to do. And
one of the main selling points of .rst was that it integrates much
more smoothly into our existing pile of .txt docs, whereas the
DocBook/ subdir was always a bit a ghetto. Forcing another split seems
ill-advised to me.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch