linux-kernel - Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <7B63766B-0F9E-417D-A101-13B9B092F64F@darmarit.de>
Date:	Wed, 29 Jun 2016 19:35:46 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jonathan Corbet <corbet@....net>
Cc:	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Dave Airlie <airlied@...il.com>,
	Jani Nikula <jani.nikula@...el.com>,
	Grant Likely <grant.likely@...retlab.ca>,
	Keith Packard <keithp@...thp.com>,
	LKML Mailing List <linux-kernel@...r.kernel.org>,
	"linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
	Hans Verkuil <hverkuil@...all.nl>,
	Randy Dunlap <rdunlap@...radead.org>
Subject: Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next

Hi Jonathan,

Am 29.06.2016 um 18:24 schrieb Jonathan Corbet <corbet@....net>:

> Hi, Markus,
> 
> I was glad to hear from you, but I have to agree with Jani: this is not
> how things are done.  Consider this one line:
> 
>> 706 files changed, 123369 insertions(+), 752 deletions(-)
> 
> Something like that will be a huge red flag to any kernel maintainer!
> 
> In the kernel community, we have spent the last 25 years figuring out a
> development model that is based on gradual, incremental changes, each of
> which can be reviewed on its own merits.  It does *not* encompass
> wholesale replacements of existing code — even in situations where that
> code was not just merged after a year of discussions, negotiations, and
> false starts.

Yes, my mistake, as I wrote to Jani.

> I simply cannot accept this pull request.
> 
> Markus, we all very much want your help in this work.  You have expertise
> and energy that could really push the documentation effort forward.  But
> it needs to be done the way kernel developers do it: cooperatively,
> incrementally, and always mindful of the entire community's needs.
> 
> I would love it if you would take the flat-table and man-page work,
> separate them out, and make them work with the *existing* Sphinx-based
> scheme.  If you can do it soon, we can maybe get it into 4.8.  Can you
> focus on that for now, please?

Yes, I will send you flat-table request in the next days.

> As for the rest, what we have now is certainly far from perfect; we're
> figuring a lot of this out as we go.  Incremental improvements are
> welcome, and each will be evaluated independently.  Please help us to
> make the kernel's documentation better that way.

I'am willing to do so, but I need some help / suggestions:

1. I have this extensions in the scripts/site-python/linuxdoc.
   What do you recommend, how could I split this up in a patch
   series which is more evaluated.

.. I wrote to Jani, that my approach was chaotic in the past
and I'am sorry for this. But now I'am sitting in front of this
bulk of source and I'am bit helpless how to split ... I will
try to make it more elaborate, but it will be helpfull if 
you point me the right direction ... 

2. What is the best way to ship these migrations

or better I asked, what is your recommendation for a
migration strategy. Jani says, that this better belongs
to authors, but I have a doubt that we end with the
migration in the next years, if we wait about every author.
I think, supporting both infrastructures - the xml and the
reST - over a long period is not the best option. What is
your recommendation on this? 

Regards

  -- Markus --
> 
> Thanks,
> 
> jon