linux-kernel - Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST

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: <20190416065815.57fbdf2c@coco.lan>
Date:   Tue, 16 Apr 2019 06:58:15 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To:     "Rafael J. Wysocki" <rafael@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>,
        "Rafael J. Wysocki" <rjw@...ysocki.net>,
        Viresh Kumar <viresh.kumar@...aro.org>,
        Linux PM <linux-pm@...r.kernel.org>
Subject: Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST

Em Tue, 16 Apr 2019 10:21:31 +0200
"Rafael J. Wysocki" <rafael@...nel.org> escreveu:

> On Tue, Apr 16, 2019 at 4:56 AM Mauro Carvalho Chehab
> <mchehab+samsung@...nel.org> wrote:
> >
> > In order to be able to build html and pdf files, convert the
> > documentation to ReST format.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>  
> 
> Please don't convert these files.
> 
> They need more work than just semi-automatic conversion

Except for one exception (at patch 32/57), the ReST conversion on this
patch set was manually made. I basically renamed the files to
.rst, checked the errors and fixed, trying to preserve the original
document style as much as possible, while providing a good visual
for the html output.

I suspect that trying to write a script for such kind of conversion
is not an easy task, as some documents within the Kernel tree have
their own personal style, (there was even one written in LaTeX at
the CDROM docs), and I suspect that a script would end by adding 
extra unwanted markups.

> and the material in them needs to go under driver-api.

Yeah, those documents make sense to be at the driver-api set. 

The rationale why I placed the patch with actually renames on a
separate patchset (already on my devel tree, but yet to be submitted)
is that, this way, it should be easy for maintainers to pick the 
conversion patch, apply on their trees, and, if they're not ready
yet, postpone the actual rename/move thing.

> This is quite hight in my TODO list.

OK. Feel free to use this patch as a starting point if you
want.

Regards,
Mauro