[net-next,0/2] docs: net: Convert netdev-FAQ to RST

Jon,

Is it ok for this to go through Dave's tree?  Patch one touches a
line in Documentation/networking/index.rst  Patch two depends on patch
one so it needs to go through the same tree please.


Dave (and Jon),

Kernel docs are prefer restructured text (RST) format.  In doing the
conversion I tried a bunch of different ways to break it up to ease
review.  Nothing I tried worked since so many of the changes touch so
many lines.  In the end I did the whole conversion as a single patch and
listed in the patch commit log each type of change that was made.

Also, with these conversions I'm finding it difficult to split the
changes into separate patches and still keep the tree sane after each
patch.

In an effort to catch mistakes I did the conversion over three days -
there is only so many times you can read a docs file in one day without
your eyes starting to bleed.

Any tips and/or suggestions on making this and future conversions easier
to review much appreciated.  If changes are not widespread it seems to
be better to split the file rename into a separate patch then make the
changes after that.  (For this one it didn't help.)


thanks,
Tobin.

Tobin C. Harding (2):
  docs: Add rest label the_canonical_path_format
  docs: net: Convert netdev-FAQ to restructured text

 Documentation/networking/index.rst           |   1 +
 Documentation/networking/netdev-FAQ.rst      | 259 +++++++++++++++++++
 Documentation/networking/netdev-FAQ.txt      | 244 -----------------
 Documentation/process/submitting-patches.rst |   1 +
 4 files changed, 261 insertions(+), 244 deletions(-)
 create mode 100644 Documentation/networking/netdev-FAQ.rst
 delete mode 100644 Documentation/networking/netdev-FAQ.txt

On Wed, Jul 25, 2018 at 12:50:03PM +1000, Tobin C. Harding wrote:

Please drop this.  I've forgotten to deal with the links from
Documentation/*.rst to Documentation/networking/netdev-FAQ.txt


Since I've already botched it can I ask for guidance here.  The problem
is updating the links means making changes that will cause merge
conflicts if they go through net-dev tree (since most references are in
Documentation/*.rst).  But we can't go through docs tree either since
that could lead to merge conflicts later as well.

My idea was to leave netdev-FAQ.txt in place but with all content
removed except

  'This file has moved to netdev-FAQ.rst. This file will be removed once
  netdev RST conversion is complete'

And then do the same for each file conversion under
Documentation/networking/.  Once all the files are converted a single
patch set updating all references into Documentation/networking/*.rst
could be posted to the docs tree.

One other idea was to leave a symlink netdev-FAQ.txt -> netdev-FAQ.rst
but I don't know how that would play with the build system (docs or
otherwise).


thanks,
Tobin.

On Wed, 25 Jul 2018 13:28:10 +1000
"Tobin C. Harding" <me@tobin.cc> wrote:

> Since I've already botched it can I ask for guidance here.  The problem
> is updating the links means making changes that will cause merge
> conflicts if they go through net-dev tree (since most references are in
> Documentation/*.rst).  But we can't go through docs tree either since
> that could lead to merge conflicts later as well.

Merge conflicts are a way of life in Documentation/ - everybody messes
with it.  They are usually pretty easy to resolve.

I only see a handful of references to netdev-FAQ.txt in the tree; I would
suggest just making the change and being done with it.  There shouldn't be
any need to do a more complicated dance than that.

And to answer your other question, yes of course it's fine (and expected)
for this to go through Dave's tree.

Thanks,

jon

On Wed, Jul 25, 2018 at 08:14:15AM -0600, Jonathan Corbet wrote:
> On Wed, 25 Jul 2018 13:28:10 +1000
> "Tobin C. Harding" <me@tobin.cc> wrote:
> 
> > Since I've already botched it can I ask for guidance here.  The problem
> > is updating the links means making changes that will cause merge
> > conflicts if they go through net-dev tree (since most references are in
> > Documentation/*.rst).  But we can't go through docs tree either since
> > that could lead to merge conflicts later as well.
> 
> Merge conflicts are a way of life in Documentation/ - everybody messes
> with it.  They are usually pretty easy to resolve.
> 
> I only see a handful of references to netdev-FAQ.txt in the tree; I would
> suggest just making the change and being done with it.  There shouldn't be
> any need to do a more complicated dance than that.

Ok, I'll re-spin with all references fixed.

> And to answer your other question, yes of course it's fine (and expected)
> for this to go through Dave's tree.

And accept abuse for all merge conflicts in person at Plumbers in November :)

Thanks,
Tobin.