Em Wed, 19 Jun 2019 08:54:58 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> [Trimming the CC list from hell made sense, but it might have been better
> to leave me on it...]
>
> On Wed, 19 Jun 2019 11:15:28 -0300
> Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote:
>
> > Em Wed, 19 Jun 2019 14:39:10 +0100
> > David Howells <dhowells@xxxxxxxxxx> escreveu:
> >
> > > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote:
> > >
> > > > > > -Documentation/nommu-mmap.rst
> > > > > > +Documentation/driver-api/nommu-mmap.rst
> > >
> > > Why is this moving to Documentation/driver-api?
> >
> > Good point. I tried to do my best with those document renames, but
> > I'm pretty sure some of them ended by going to the wrong place - or
> > at least there are arguments in favor of moving it to different
> > places :-)
>
> I think that a lot of this might also be an argument for slowing down just
> a little bit. I really don't think that blasting through and reformatting
> all of our text documents is the most urgent problem right now and, in
> cases like this, it might create others.
>
> Organization of the documentation tree is important; it has never really
> gotten any attention so far, and we're trying to make it better. But
> moving documents will, by its nature, annoy people. We can generally get
> past that, but I'd really like to avoid moving things twice. In general,
> I would rather see a single document converted, read critically and
> updated, and carefully integrated with the rest than a hundred of them
> swept into different piles...
>
> See what I'm getting at?
I see what you mean, and I agree with this principle. That's basically
why I split the patches into two groups.
The first group (with comes first) does just the conversion
and renames from txt to rst, adding a :orphan: to the stuff that was
just converted.
On this series, those are patches 1 to 11. I was already expecting
some heat on patch 1.
The next group of patches do the renaming part. Those are the ones that
actually took me a lot more time, as I needed to quickly read several docs
in order to understand what's happening, before proposing a change.
That's also the group of patches were I expect more active comments,
as there are several cases where this is not obvious.
Yet, from what I saw, there are some documents that sounds easy to
move, like Documentation/laptops, with (except if I missed something)
clearly belongs to admin-guide.
Applying the second patch series and patches 2 to 11 from this third
series is, IMHO, a good thing to do.
-
IMO, patches 1 and 12 are important, as, after those patches, the
/Documentation dir becomes a lot cleaner:
$ ls -F Documentation/
ABI/ fb/ locking/ s390/
accounting/ features/ logo.gif scheduler/
acpi/ filesystems/ logo.txt scsi/
admin-guide/ firmware_class/ m68k/ security/
arm/ firmware-guide/ maintainer/ sh/
arm64/ fpga/ Makefile sound/
auxdisplay/ gpio/ media/ sparc/
block/ gpu/ mic/ sphinx/
bpf/ hid/ mips/ sphinx-static/
cdrom/ hwmon/ misc-devices/ spi/
Changes@ i2c/ Module.symvers SubmittingPatches
CodingStyle ia64/ netlabel/ target/
conf.py ide/ networking/ timers/
core-api/ iio/ nios2/ trace/
cpu-freq/ index.rst openrisc/ translations/
crypto/ infiniband/ output/ usb/
devicetree/ input/ packing.txt userspace-api/
dev-tools/ ioctl/ parisc/ virtual/
DocBook/ IPMB.txt PCI/ vm/
doc-guide/ isdn/ pcmcia/ w1/
docutils.conf kbuild/ power/ watchdog/
dontdiff Kconfig powerpc/ wimax/
driver-api/ kernel-hacking/ process/ x86/
EDID/ leds/ RCU/ xtensa/
fault-injection/ livepatch/ riscv/
Being easy to identify when someone tries to add a new text file there
without thinking on where it would fit[1], and to reorganize the
directory tree in a way that it will fit our needs.
[1] Btw, there are some two files at linux-next, incrementally
increasing the Documentation/ mess:
IPMB.txt and packing.txt.
Added on those commits:
commit 51bd6f291583684f495ea498984dfc22049d7fd2
Author: Asmaa Mnebhi <Asmaa@xxxxxxxxxxxx>
Date: Mon Jun 10 14:57:02 2019 -0400
Add support for IPMB driver
commit 554aae35007e49f533d3d10e788295f7141725bc
Author: Vladimir Oltean <olteanv@xxxxxxxxx>
Date: Thu May 2 23:23:29 2019 +0300
lib: Add support for generic packing operations
We'll never finish organizing documents while people don't stop
adding new files to Documentation/ directory.
Thanks,
Mauro
