[v2,14/24] docs: cpu-freq: convert index.txt to ReST

Commit Message

Mauro Carvalho Chehab Feb. 17, 2020, 4:20 p.m. UTC

most of the stuff there can be re-used with ReST format,
but we need to add an empty TOC and remove the existing
entries, as the following conversion patches will be re-adding
them, as they're converted.

Signed-off-by: Mauro Carvalho Chehab <[e-mail]>
---
 Documentation/cpu-freq/index.rst | 35 ++++++++++++++++++++
 Documentation/cpu-freq/index.txt | 56 --------------------------------
 Documentation/index.rst          |  1 +
 3 files changed, 36 insertions(+), 56 deletions(-)
 create mode 100644 Documentation/cpu-freq/index.rst
 delete mode 100644 Documentation/cpu-freq/index.txt

Comments

Rafael J. Wysocki Feb. 17, 2020, 8:06 p.m. UTC | #1

On Mon, Feb 17, 2020 at 5:20 PM Mauro Carvalho Chehab
<[e-mail]> wrote:
>
> most of the stuff there can be re-used with ReST format,
> but we need to add an empty TOC and remove the existing
> entries, as the following conversion patches will be re-adding
> them, as they're converted.

I see a very little value in converting the files in the cpu-freq
directory from .txt to .rst, which I have told you at least twice.

They are just old-style driver API documents for cpufreq, but moving
them under driver-api/ as they are would not be a good idea IMO,
because at least some of them are outdated (note that the admin-guide
part of the cpufreq documentation, in the .rst format, is located
under admin-guide/).

I haven't had the time to write a proper replacement for them yet and
honestly I find it quite obnoxious to see these reoccurring attempts
to blindly convert them to .rst without taking care of their contents
and location.

I will take care of these files at one point as promised, but that's
not going to happen today or tomorrow and please just leave them alone
if that is not a big deal.

Thanks!

> Signed-off-by: Mauro Carvalho Chehab <[e-mail]>
> ---
>  Documentation/cpu-freq/index.rst | 35 ++++++++++++++++++++
>  Documentation/cpu-freq/index.txt | 56 --------------------------------
>  Documentation/index.rst          |  1 +
>  3 files changed, 36 insertions(+), 56 deletions(-)
>  create mode 100644 Documentation/cpu-freq/index.rst
>  delete mode 100644 Documentation/cpu-freq/index.txt
>
> diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst
> new file mode 100644
> index 000000000000..1bff3dfddd23
> --- /dev/null
> +++ b/Documentation/cpu-freq/index.rst
> @@ -0,0 +1,35 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============================================================================
> +Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel
> +==============================================================================
> +
> +Author: Dominik Brodowski  <[e-mail]>
> +
> +   Clock scaling allows you to change the clock speed of the CPUs on the
> +   fly. This is a nice method to save battery power, because the lower
> +   the clock speed, the less power the CPU consumes.
> +
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +Mailing List
> +------------
> +There is a CPU frequency changing CVS commit and general list where
> +you can report bugs, problems or submit patches. To post a message,
> +send an email to [e-mail].
> +
> +Links
> +-----
> +the FTP archives:
> +* ftp://ftp.linux.org.uk/pub/linux/cpufreq/
> +
> +how to access the CVS repository:
> +* http://cvs.arm.linux.org.uk/
> +
> +the CPUFreq Mailing list:
> +* http://vger.kernel.org/vger-lists.html#linux-pm
> +
> +Clock and voltage scaling for the SA-1100:
> +* http://www.lartmaker.nl/projects/scaling
> diff --git a/Documentation/cpu-freq/index.txt b/Documentation/cpu-freq/index.txt
> deleted file mode 100644
> index c15e75386a05..000000000000
> --- a/Documentation/cpu-freq/index.txt
> +++ /dev/null
> @@ -1,56 +0,0 @@
> -     CPU frequency and voltage scaling code in the Linux(TM) kernel
> -
> -
> -                        L i n u x    C P U F r e q
> -
> -
> -
> -
> -                   Dominik Brodowski  <[e-mail]>
> -
> -
> -
> -   Clock scaling allows you to change the clock speed of the CPUs on the
> -    fly. This is a nice method to save battery power, because the lower
> -            the clock speed, the less power the CPU consumes.
> -
> -
> -
> -Documents in this directory:
> -----------------------------
> -
> -amd-powernow.txt -     AMD powernow driver specific file.
> -
> -core.txt       -       General description of the CPUFreq core and
> -                       of CPUFreq notifiers.
> -
> -cpu-drivers.txt -      How to implement a new cpufreq processor driver.
> -
> -cpufreq-nforce2.txt -  nVidia nForce2 platform specific file.
> -
> -cpufreq-stats.txt -    General description of sysfs cpufreq stats.
> -
> -index.txt      -       File index, Mailing list and Links (this document)
> -
> -pcc-cpufreq.txt -      PCC cpufreq driver specific file.
> -
> -
> -Mailing List
> -------------
> -There is a CPU frequency changing CVS commit and general list where
> -you can report bugs, problems or submit patches. To post a message,
> -send an email to [e-mail].
> -
> -Links
> ------
> -the FTP archives:
> -* ftp://ftp.linux.org.uk/pub/linux/cpufreq/
> -
> -how to access the CVS repository:
> -* http://cvs.arm.linux.org.uk/
> -
> -the CPUFreq Mailing list:
> -* http://vger.kernel.org/vger-lists.html#linux-pm
> -
> -Clock and voltage scaling for the SA-1100:
> -* http://www.lartmaker.nl/projects/scaling
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index e99d0bd2589d..4cf37ad1cd1d 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -99,6 +99,7 @@ needed).
>     accounting/index
>     block/index
>     cdrom/index
> +   cpu-freq/index
>     ide/index
>     fb/index
>     fpga/index
> --
> 2.24.1
>

Mauro Carvalho Chehab Feb. 28, 2020, 9:14 a.m. UTC | #2

Hi Rafael,

Em Mon, 17 Feb 2020 21:06:20 +0100
"Rafael J. Wysocki" <[e-mail]> escreveu:

> On Mon, Feb 17, 2020 at 5:20 PM Mauro Carvalho Chehab
> <[e-mail]> wrote:
> >
> > most of the stuff there can be re-used with ReST format,
> > but we need to add an empty TOC and remove the existing
> > entries, as the following conversion patches will be re-adding
> > them, as they're converted.  
> 
> I see a very little value in converting the files in the cpu-freq
> directory from .txt to .rst, which I have told you at least twice.
> 
> They are just old-style driver API documents for cpufreq, but moving
> them under driver-api/ as they are would not be a good idea IMO,
> because at least some of them are outdated (note that the admin-guide
> part of the cpufreq documentation, in the .rst format, is located
> under admin-guide/).
> 
> I haven't had the time to write a proper replacement for them yet and
> honestly I find it quite obnoxious to see these reoccurring attempts
> to blindly convert them to .rst without taking care of their contents
> and location.
> 
> I will take care of these files at one point as promised, but that's
> not going to happen today or tomorrow and please just leave them alone
> if that is not a big deal.

Sorry, I completely forgot that you asked to skip the old cpufreq docs.
My bad!

The thing is that I have now fully converted all docs to ReST (with a
handful exceptions for things that may not make sense to convert, like
configuration files that ends with .txt).

As a matter of helping those (like me) that are trying to finish this
huge conversion/reorganize task, I would very much prefer to keep those
files converted somewhere (or trashed, if their contents is now completely
garbage).

One of the things we discussed at linux-doc ML is to create a "staging"
area where we can place:

- things that aren't ready to be at the main documentation body yet;
- too obsolete docs that may require major work;
- things that we didn't find a good place to put yet.

From the last discussions, it seems we reach a consensus about creating that.

So, I should be preparing a separate patchset adding a Documentation/staging
dir. 

Would it be OK for you if I change the cpufreq patches on this series to
be moving those into a new Documentation/staging/cpufreq directory?

Regards,
Mauro

Rafael J. Wysocki Feb. 28, 2020, 9:33 a.m. UTC | #3

On Fri, Feb 28, 2020 at 10:14 AM Mauro Carvalho Chehab
<[e-mail]> wrote:
>
> Hi Rafael,
>
> Em Mon, 17 Feb 2020 21:06:20 +0100
> "Rafael J. Wysocki" <[e-mail]> escreveu:
>
> > On Mon, Feb 17, 2020 at 5:20 PM Mauro Carvalho Chehab
> > <[e-mail]> wrote:
> > >
> > > most of the stuff there can be re-used with ReST format,
> > > but we need to add an empty TOC and remove the existing
> > > entries, as the following conversion patches will be re-adding
> > > them, as they're converted.
> >
> > I see a very little value in converting the files in the cpu-freq
> > directory from .txt to .rst, which I have told you at least twice.
> >
> > They are just old-style driver API documents for cpufreq, but moving
> > them under driver-api/ as they are would not be a good idea IMO,
> > because at least some of them are outdated (note that the admin-guide
> > part of the cpufreq documentation, in the .rst format, is located
> > under admin-guide/).
> >
> > I haven't had the time to write a proper replacement for them yet and
> > honestly I find it quite obnoxious to see these reoccurring attempts
> > to blindly convert them to .rst without taking care of their contents
> > and location.
> >
> > I will take care of these files at one point as promised, but that's
> > not going to happen today or tomorrow and please just leave them alone
> > if that is not a big deal.
>
> Sorry, I completely forgot that you asked to skip the old cpufreq docs.
> My bad!
>
> The thing is that I have now fully converted all docs to ReST (with a
> handful exceptions for things that may not make sense to convert, like
> configuration files that ends with .txt).

And I have this patch:

https://patchwork.kernel.org/patch/11411035/

so at least please drop the commits converting the three files affected by it.

> As a matter of helping those (like me) that are trying to finish this
> huge conversion/reorganize task, I would very much prefer to keep those
> files converted somewhere (or trashed, if their contents is now completely
> garbage).
>
> One of the things we discussed at linux-doc ML is to create a "staging"
> area where we can place:
>
> - things that aren't ready to be at the main documentation body yet;
> - too obsolete docs that may require major work;
> - things that we didn't find a good place to put yet.
>
> From the last discussions, it seems we reach a consensus about creating that.

So the other files in Documentation/cpu-freq/ can be converted to .rst
as far as I'm concerned (even though I still don't see much value in
doing that, just for the record).

They will be going away anyway in the future, regardless of the format
in which they are at that time. :-)

Cheers!

Jonathan Corbet March 2, 2020, 9:19 p.m. UTC | #4

On Mon, 17 Feb 2020 17:20:32 +0100
Mauro Carvalho Chehab <[e-mail]> wrote:

> most of the stuff there can be re-used with ReST format,
> but we need to add an empty TOC and remove the existing
> entries, as the following conversion patches will be re-adding
> them, as they're converted.
> 
> Signed-off-by: Mauro Carvalho Chehab <[e-mail]>

Rafael, do you want to carry the cpu-freq changes from this set, or should
I just apply the whole thing over here?

Thanks,

jon

Rafael J. Wysocki March 2, 2020, 10:16 p.m. UTC | #5

On Mon, Mar 2, 2020 at 10:19 PM Jonathan Corbet <[e-mail]> wrote:
>
> On Mon, 17 Feb 2020 17:20:32 +0100
> Mauro Carvalho Chehab <[e-mail]> wrote:
>
> > most of the stuff there can be re-used with ReST format,
> > but we need to add an empty TOC and remove the existing
> > entries, as the following conversion patches will be re-adding
> > them, as they're converted.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[e-mail]>
>
> Rafael, do you want to carry the cpu-freq changes from this set, or should
> I just apply the whole thing over here?

I will take the ones that are applicable after rebasing on top of
https://patchwork.kernel.org/patch/11411035/

Cheers!

Mauro Carvalho Chehab March 3, 2020, 1:54 p.m. UTC | #6

Em Mon, 2 Mar 2020 23:16:10 +0100
"Rafael J. Wysocki" <[e-mail]> escreveu:

> On Mon, Mar 2, 2020 at 10:19 PM Jonathan Corbet <[e-mail]> wrote:
> >
> > On Mon, 17 Feb 2020 17:20:32 +0100
> > Mauro Carvalho Chehab <[e-mail]> wrote:
> >  
> > > most of the stuff there can be re-used with ReST format,
> > > but we need to add an empty TOC and remove the existing
> > > entries, as the following conversion patches will be re-adding
> > > them, as they're converted.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <[e-mail]>  
> >
> > Rafael, do you want to carry the cpu-freq changes from this set, or should
> > I just apply the whole thing over here?  
> 
> I will take the ones that are applicable after rebasing on top of
> https://patchwork.kernel.org/patch/11411035/

Just rebased on the top of it (plus next-20200303) and sent.

Btw, patch 1/5 of such series is just a small fix for the above. It
addresses a Kconfig.x86 pointer to a documentation file that were moved
by the above patch. 

Feel free to merge it with patch #11411035 if you want.

Regards,
Mauro

Mauro Carvalho Chehab March 3, 2020, 2:01 p.m. UTC | #7

Em Mon, 2 Mar 2020 14:19:16 -0700
Jonathan Corbet <[e-mail]> escreveu:

> On Mon, 17 Feb 2020 17:20:32 +0100
> Mauro Carvalho Chehab <[e-mail]> wrote:
> 
> > most of the stuff there can be re-used with ReST format,
> > but we need to add an empty TOC and remove the existing
> > entries, as the following conversion patches will be re-adding
> > them, as they're converted.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <[e-mail]>  
> 
> Rafael, do you want to carry the cpu-freq changes from this set, or should
> I just apply the whole thing over here?

Hi Jon,

As Rafael should be applying the cpu-freq via his tree, I'm re-sending the
remaining patches on this series as:

	[PATCH v3 00/18] Manually convert  thermal, crypto and misc devices to ReST

Regards,
Mauro

Patch

diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst
new file mode 100644
index 000000000000..1bff3dfddd23
--- /dev/null
+++ b/Documentation/cpu-freq/index.rst
@@ -0,0 +1,35 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================================================================
+Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel
+==============================================================================
+
+Author: Dominik Brodowski  <[e-mail]>
+
+   Clock scaling allows you to change the clock speed of the CPUs on the
+   fly. This is a nice method to save battery power, because the lower
+   the clock speed, the less power the CPU consumes.
+
+
+.. toctree::
+   :maxdepth: 1
+
+Mailing List
+------------
+There is a CPU frequency changing CVS commit and general list where
+you can report bugs, problems or submit patches. To post a message,
+send an email to [e-mail].
+
+Links
+-----
+the FTP archives:
+* ftp://ftp.linux.org.uk/pub/linux/cpufreq/
+
+how to access the CVS repository:
+* http://cvs.arm.linux.org.uk/
+
+the CPUFreq Mailing list:
+* http://vger.kernel.org/vger-lists.html#linux-pm
+
+Clock and voltage scaling for the SA-1100:
+* http://www.lartmaker.nl/projects/scaling
diff --git a/Documentation/cpu-freq/index.txt b/Documentation/cpu-freq/index.txt
deleted file mode 100644
index c15e75386a05..000000000000
--- a/Documentation/cpu-freq/index.txt
+++ /dev/null
@@ -1,56 +0,0 @@ 
-     CPU frequency and voltage scaling code in the Linux(TM) kernel
-
-
-		         L i n u x    C P U F r e q
-
-
-
-
-		    Dominik Brodowski  <[e-mail]>
-
-
-
-   Clock scaling allows you to change the clock speed of the CPUs on the
-    fly. This is a nice method to save battery power, because the lower
-            the clock speed, the less power the CPU consumes.
-
-
-
-Documents in this directory:
-----------------------------
-
-amd-powernow.txt -	AMD powernow driver specific file.
-
-core.txt	-	General description of the CPUFreq core and
-			of CPUFreq notifiers.
-
-cpu-drivers.txt -	How to implement a new cpufreq processor driver.
-
-cpufreq-nforce2.txt -	nVidia nForce2 platform specific file.
-
-cpufreq-stats.txt -	General description of sysfs cpufreq stats.
-
-index.txt	-	File index, Mailing list and Links (this document)
-
-pcc-cpufreq.txt -	PCC cpufreq driver specific file.
-
-
-Mailing List
-------------
-There is a CPU frequency changing CVS commit and general list where
-you can report bugs, problems or submit patches. To post a message,
-send an email to [e-mail].
-
-Links
------
-the FTP archives:
-* ftp://ftp.linux.org.uk/pub/linux/cpufreq/
-
-how to access the CVS repository:
-* http://cvs.arm.linux.org.uk/
-
-the CPUFreq Mailing list:
-* http://vger.kernel.org/vger-lists.html#linux-pm
-
-Clock and voltage scaling for the SA-1100:
-* http://www.lartmaker.nl/projects/scaling
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e99d0bd2589d..4cf37ad1cd1d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -99,6 +99,7 @@  needed).
    accounting/index
    block/index
    cdrom/index
+   cpu-freq/index
    ide/index
    fb/index
    fpga/index