ABI conversion to ReST - Was: Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Jon,

Em Sun, 23 Oct 2016 09:20:00 -0200
Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu:

> Em Sat, 22 Oct 2016 08:56:29 -0200
> Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu:
> 
> > How many special-case commands are we going to need to run?  Does it  
> > > really need to go beyond what parse-headers is doing now?    
> > 
> > Right now, we have actually 2 such cases: kernel-doc and parse-headers.
> > 
> > I also use a set of perl scripts that I manually run, on each Kernel
> > version, to update the cards list of several drivers. It is a total of
> > 9 such scripts.  
> 
> I ended by adding a few more scripts, as ivtv, tm6000 and gspca
> cardlists were missing. As result, all three had some documentation
> gaps.
> 
> As an example of such scripts, I added a PoC patch at my development
> tree, at the lkml-books-v2 branch:
> 
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books-v2
> 
> Patch follows.

Today, I converted the EDAC documentation to ReST, but there is one
left over: the EDAC documentation under Documentation/ABI.

I suspect this is something for discussions at the KS too, but let me
put some insights about the ABI directory.

It is probably worth to add at the admin's guide or as a separate guide
at least for configfs and sysfs, but:

1) manually converting all those files would be very painful;
2) a patch series with such conversion would be very hard to
   be merged, as it would likely cause all sorts of conflicts
   with maintainers' trees that update it.
2) the actual format there is a database, with is not too nice for
   an Admin's guide;

So, if we're willing to create a guide with the userspace API defined
there, it is probably better to write a parser script that would
convert it into a documentation, without requiring any changes there.

As defined at Documentation/ABI/README, this is actually a database
with those fields:

What, Date, KernelVersion, Contact, Description and Users.

An user-face documentation would probably require only a few of those
fields (like What and Description), but the entries should be
probably sorted by the What field.

So, I suspect it wouldn't be hard to write a perl script to parse it
and generate an ABI guide. On the other hand, we might need to fix
some documents, if the parser fails due to some typo.

Comments?

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux