linux-kernel - Re: [PATCH 00/10] Add all documentation files to an html/pdf produced book

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: <20190412062826.7681c803@coco.lan>
Date:   Fri, 12 Apr 2019 06:28:26 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH 00/10] Add all documentation files to an html/pdf
 produced book

Em Thu, 11 Apr 2019 12:49:04 -0600
Jonathan Corbet <corbet@....net> escreveu:

> On Wed, 10 Apr 2019 06:49:39 -0300
> Mauro Carvalho Chehab <mchehab+samsung@...nel.org> wrote:
> 
> [I'm just responding to one little piece of this for the moment...]
> 
> > In any case, IMHO, the best would be to add a new
> > crap^h^h^h^hstaging group were we could place all legacy random stuff.
> > Then, gradually fix those, splitting stuff and promoting them to the
> > main books, in a similar way to what we do with staging.  
> 
> Now that's an interesting idea; I hadn't thought about that.  Doing so,
> though, implies a willingness to stage unloved docs *out*,

That sounds like a plus! 

> and my experience is that there is little appetite for that. 

Heh, I guess most of us are biased to avoid dropping stuff. Yet, it
happens with time. I wouldn't mind dropping something too outdated
if, after some time, nobody fixes the issues there.

> It also kind of
> implies moving docs twice - at least for the ones that get updates - and
> that may not be entirely appreciated.

True, but avoiding moving twice is not trivial. I mean, files
need to be renamed anyway. Only if we get it right the first
time (converting the file and placing at the right place), we'll
avoid a double move.

I considered an alternative of just including a *.txt file
at a ReST TOC, but Sphinx doesn't allow including a file that
it is not specified at source_suffix. Worse than that, if a
suffix is added there, it will parse (and crash) if the file
has things like:
        some indented title
        ===================

or even:
	- item
	- ....

With a sort of pattern that we have on several text files.

There's an alternative: we could have an "index_staging.rst" file
with the documents that require serious work. So, instead of
actually moving stuff, we'll just place their location there
(but files still need to be renamed). When the document is fixed,
all we need is to move from the staging index to the main one.

> > > I feel like it would, if anything, reduce the incentive to
> > > deal with these leftover documents properly.      
> > 
> > IMHO, it is just the opposite. Let's face it: ReST build was added around
> > May, 2016, for Kernel 4.7. People had quite some time and kernel versions
> > to do conversions. If nothing is done, I doubt we would have any boom on
> > patches addressing the issues.  
> 
> So I don't have any hard numbers, but my feeling is that this work is
> continuing apace and perhaps even picking up.  Certainly I'm having a
> harder time keeping up with it, even when you're busy with other things :)
> These things take time; I'm not really ready to give up on it yet.

Ok. I'm working on a series of patches converting stuff from some random
subsystems. I should be sending the series soon.


Thanks,
Mauro