* [PATCH v3 00/29] Convert files to ReST - part 2
@ 2020-04-27 21:16 Mauro Carvalho Chehab
2020-04-27 21:17 ` [PATCH v3 23/29] docs: filesystems: convert spufs/spufs.txt to ReST Mauro Carvalho Chehab
2020-04-28 19:01 ` [PATCH v3 00/29] Convert files to ReST - part 2 Jonathan Corbet
0 siblings, 2 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-27 21:16 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Jonathan Corbet, Mauro Carvalho Chehab, linux-usb, linux-kernel,
codalist, linux-xfs, linux-cachefs, linux-fsdevel, linuxppc-dev
This is the second part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's linux-next,
at tag next-20190617.
The first version of this series had 57 patches. The first part with 28 patches
were already merged. Right now, there are still ~76 patches pending applying
(including this series), and that's because I opted to do ~1 patch per converted
directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts for the conversion, plus a final patch adding orphaned books
to existing ones.
Those patches should probably be good to be merged either by subsystem
maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement, after I
submit the third part.
Both this series and the other parts of this work are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v5.1
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
It contains all pending work from my side related to the conversion, plus
the patches I finished a first version today with contains the renaming
patches and de-orphan changes.
---
Version 3:
- Rebased on the top of next-20200424
- configfs.rst conversion moved to the end of the series;
- avoided almost all markups at configfs.rst while still preserving
a reasonable output and not generating build warnings.
Version 2:
- Removed patches merged via other trees;
- rebased on the top of today's linux-next (next-20190617);
- Fix a typo on one patch's description;
- Added received acks.
Mauro Carvalho Chehab (29):
docs: filesystems: convert caching/object.txt to ReST
docs: filesystems: convert caching/fscache.txt to ReST format
docs: filesystems: caching/netfs-api.txt: convert it to ReST
docs: filesystems: caching/operations.txt: convert it to ReST
docs: filesystems: caching/cachefiles.txt: convert to ReST
docs: filesystems: caching/backend-api.txt: convert it to ReST
docs: filesystems: convert cifs/cifsroot.txt to ReST
docs: filesystems: convert automount-support.txt to ReST
docs: filesystems: convert coda.txt to ReST
docs: filesystems: convert devpts.txt to ReST
docs: filesystems: convert dnotify.txt to ReST
docs: filesystems: convert fiemap.txt to ReST
docs: filesystems: convert files.txt to ReST
docs: filesystems: convert fuse-io.txt to ReST
docs: filesystems: convert locks.txt to ReST
docs: filesystems: convert mandatory-locking.txt to ReST
docs: filesystems: convert mount_api.txt to ReST
docs: filesystems: convert quota.txt to ReST
docs: filesystems: convert seq_file.txt to ReST
docs: filesystems: convert sharedsubtree.txt to ReST
docs: filesystems: split spufs.txt into 3 separate files
docs: filesystems: convert spufs/spu_create.txt to ReST
docs: filesystems: convert spufs/spufs.txt to ReST
docs: filesystems: convert spufs/spu_run.txt to ReST
docs: filesystems: convert sysfs-pci.txt to ReST
docs: filesystems: convert sysfs-tagging.txt to ReST
docs: filesystems: convert xfs-delayed-logging-design.txt to ReST
docs: filesystems: convert xfs-self-describing-metadata.txt to ReST
docs: filesystems: convert configfs.txt to ReST
Documentation/admin-guide/sysctl/kernel.rst | 2 +-
...ount-support.txt => automount-support.rst} | 23 +-
.../{backend-api.txt => backend-api.rst} | 165 +-
.../{cachefiles.txt => cachefiles.rst} | 139 +-
Documentation/filesystems/caching/fscache.rst | 565 ++++++
Documentation/filesystems/caching/fscache.txt | 448 -----
Documentation/filesystems/caching/index.rst | 14 +
.../caching/{netfs-api.txt => netfs-api.rst} | 172 +-
.../caching/{object.txt => object.rst} | 43 +-
.../{operations.txt => operations.rst} | 45 +-
.../cifs/{cifsroot.txt => cifsroot.rst} | 56 +-
Documentation/filesystems/coda.rst | 1670 ++++++++++++++++
Documentation/filesystems/coda.txt | 1676 -----------------
.../{configfs/configfs.txt => configfs.rst} | 131 +-
Documentation/filesystems/devpts.rst | 36 +
Documentation/filesystems/devpts.txt | 26 -
.../filesystems/{dnotify.txt => dnotify.rst} | 11 +-
.../filesystems/{fiemap.txt => fiemap.rst} | 133 +-
.../filesystems/{files.txt => files.rst} | 15 +-
.../filesystems/{fuse-io.txt => fuse-io.rst} | 6 +
Documentation/filesystems/index.rst | 23 +
.../filesystems/{locks.txt => locks.rst} | 14 +-
...tory-locking.txt => mandatory-locking.rst} | 25 +-
.../{mount_api.txt => mount_api.rst} | 329 ++--
Documentation/filesystems/proc.rst | 2 +-
.../filesystems/{quota.txt => quota.rst} | 41 +-
.../{seq_file.txt => seq_file.rst} | 61 +-
.../{sharedsubtree.txt => sharedsubtree.rst} | 394 ++--
Documentation/filesystems/spufs/index.rst | 13 +
.../filesystems/spufs/spu_create.rst | 131 ++
Documentation/filesystems/spufs/spu_run.rst | 138 ++
.../{spufs.txt => spufs/spufs.rst} | 304 +--
.../{sysfs-pci.txt => sysfs-pci.rst} | 23 +-
.../{sysfs-tagging.txt => sysfs-tagging.rst} | 22 +-
...ign.txt => xfs-delayed-logging-design.rst} | 65 +-
...a.txt => xfs-self-describing-metadata.rst} | 182 +-
Documentation/iio/iio_configfs.rst | 2 +-
Documentation/usb/gadget_configfs.rst | 4 +-
MAINTAINERS | 14 +-
fs/cachefiles/Kconfig | 4 +-
fs/coda/Kconfig | 2 +-
fs/configfs/inode.c | 2 +-
fs/configfs/item.c | 2 +-
fs/fscache/Kconfig | 8 +-
fs/fscache/cache.c | 8 +-
fs/fscache/cookie.c | 2 +-
fs/fscache/object.c | 4 +-
fs/fscache/operation.c | 2 +-
fs/locks.c | 2 +-
include/linux/configfs.h | 2 +-
include/linux/fs_context.h | 2 +-
include/linux/fscache-cache.h | 4 +-
include/linux/fscache.h | 42 +-
include/linux/lsm_hooks.h | 2 +-
54 files changed, 3843 insertions(+), 3408 deletions(-)
rename Documentation/filesystems/{automount-support.txt => automount-support.rst} (92%)
rename Documentation/filesystems/caching/{backend-api.txt => backend-api.rst} (87%)
rename Documentation/filesystems/caching/{cachefiles.txt => cachefiles.rst} (90%)
create mode 100644 Documentation/filesystems/caching/fscache.rst
delete mode 100644 Documentation/filesystems/caching/fscache.txt
create mode 100644 Documentation/filesystems/caching/index.rst
rename Documentation/filesystems/caching/{netfs-api.txt => netfs-api.rst} (91%)
rename Documentation/filesystems/caching/{object.txt => object.rst} (95%)
rename Documentation/filesystems/caching/{operations.txt => operations.rst} (90%)
rename Documentation/filesystems/cifs/{cifsroot.txt => cifsroot.rst} (72%)
create mode 100644 Documentation/filesystems/coda.rst
delete mode 100644 Documentation/filesystems/coda.txt
rename Documentation/filesystems/{configfs/configfs.txt => configfs.rst} (87%)
create mode 100644 Documentation/filesystems/devpts.rst
delete mode 100644 Documentation/filesystems/devpts.txt
rename Documentation/filesystems/{dnotify.txt => dnotify.rst} (90%)
rename Documentation/filesystems/{fiemap.txt => fiemap.rst} (70%)
rename Documentation/filesystems/{files.txt => files.rst} (95%)
rename Documentation/filesystems/{fuse-io.txt => fuse-io.rst} (95%)
rename Documentation/filesystems/{locks.txt => locks.rst} (91%)
rename Documentation/filesystems/{mandatory-locking.txt => mandatory-locking.rst} (91%)
rename Documentation/filesystems/{mount_api.txt => mount_api.rst} (79%)
rename Documentation/filesystems/{quota.txt => quota.rst} (81%)
rename Documentation/filesystems/{seq_file.txt => seq_file.rst} (92%)
rename Documentation/filesystems/{sharedsubtree.txt => sharedsubtree.rst} (72%)
create mode 100644 Documentation/filesystems/spufs/index.rst
create mode 100644 Documentation/filesystems/spufs/spu_create.rst
create mode 100644 Documentation/filesystems/spufs/spu_run.rst
rename Documentation/filesystems/{spufs.txt => spufs/spufs.rst} (57%)
rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (92%)
rename Documentation/filesystems/{sysfs-tagging.txt => sysfs-tagging.rst} (72%)
rename Documentation/filesystems/{xfs-delayed-logging-design.txt => xfs-delayed-logging-design.rst} (97%)
rename Documentation/filesystems/{xfs-self-describing-metadata.txt => xfs-self-describing-metadata.rst} (83%)
--
2.25.4
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v3 23/29] docs: filesystems: convert spufs/spufs.txt to ReST
2020-04-27 21:16 [PATCH v3 00/29] Convert files to ReST - part 2 Mauro Carvalho Chehab
@ 2020-04-27 21:17 ` Mauro Carvalho Chehab
2020-04-28 19:01 ` [PATCH v3 00/29] Convert files to ReST - part 2 Jonathan Corbet
1 sibling, 0 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-27 21:17 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Jeremy Kerr, linuxppc-dev, linux-kernel,
Jonathan Corbet
This file is at groff output format. Manually convert it to
ReST format, trying to preserve a similar output after parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/filesystems/spufs/index.rst | 1 +
.../spufs/{spufs.txt => spufs.rst} | 59 +++++++++----------
MAINTAINERS | 2 +-
3 files changed, 30 insertions(+), 32 deletions(-)
rename Documentation/filesystems/spufs/{spufs.txt => spufs.rst} (95%)
diff --git a/Documentation/filesystems/spufs/index.rst b/Documentation/filesystems/spufs/index.rst
index 39553c6ebefd..939cf59a7d9e 100644
--- a/Documentation/filesystems/spufs/index.rst
+++ b/Documentation/filesystems/spufs/index.rst
@@ -8,4 +8,5 @@ SPU Filesystem
.. toctree::
:maxdepth: 1
+ spufs
spu_create
diff --git a/Documentation/filesystems/spufs/spufs.txt b/Documentation/filesystems/spufs/spufs.rst
similarity index 95%
rename from Documentation/filesystems/spufs/spufs.txt
rename to Documentation/filesystems/spufs/spufs.rst
index caf36aaae804..8a42859bb100 100644
--- a/Documentation/filesystems/spufs/spufs.txt
+++ b/Documentation/filesystems/spufs/spufs.rst
@@ -1,12 +1,18 @@
-SPUFS(2) Linux Programmer's Manual SPUFS(2)
+.. SPDX-License-Identifier: GPL-2.0
+=====
+spufs
+=====
+Name
+====
-NAME
spufs - the SPU file system
-DESCRIPTION
+Description
+===========
+
The SPU file system is used on PowerPC machines that implement the Cell
Broadband Engine Architecture in order to access Synergistic Processor
Units (SPUs).
@@ -21,7 +27,9 @@ DESCRIPTION
ally add or remove files.
-MOUNT OPTIONS
+Mount Options
+=============
+
uid=<uid>
set the user owning the mount point, the default is 0 (root).
@@ -29,7 +37,9 @@ MOUNT OPTIONS
set the group owning the mount point, the default is 0 (root).
-FILES
+Files
+=====
+
The files in spufs mostly follow the standard behavior for regular sys-
tem calls like read(2) or write(2), but often support only a subset of
the operations supported on regular file systems. This list details the
@@ -125,14 +135,12 @@ FILES
space is available for writing.
- /mbox_stat
- /ibox_stat
- /wbox_stat
+ /mbox_stat, /ibox_stat, /wbox_stat
Read-only files that contain the length of the current queue, i.e. how
many words can be read from mbox or ibox or how many words can be
written to wbox without blocking. The files can be read only in 4-byte
units and return a big-endian binary integer number. The possible
- operations on an open *box_stat file are:
+ operations on an open ``*box_stat`` file are:
read(2)
If a count smaller than four is requested, read returns -1 and
@@ -143,12 +151,7 @@ FILES
in EAGAIN.
- /npc
- /decr
- /decr_status
- /spu_tag_mask
- /event_mask
- /srr0
+ /npc, /decr, /decr_status, /spu_tag_mask, /event_mask, /srr0
Internal registers of the SPU. The representation is an ASCII string
with the numeric value of the next instruction to be executed. These
can be used in read/write mode for debugging, but normal operation of
@@ -157,17 +160,14 @@ FILES
The contents of these files are:
+ =================== ===================================
npc Next Program Counter
-
decr SPU Decrementer
-
decr_status Decrementer Status
-
spu_tag_mask MFC tag mask for SPU DMA
-
event_mask Event mask for SPU interrupts
-
srr0 Interrupt Return address register
+ =================== ===================================
The possible operations on an open npc, decr, decr_status,
@@ -206,8 +206,7 @@ FILES
from the data buffer, updating the value of the fpcr register.
- /signal1
- /signal2
+ /signal1, /signal2
The two signal notification channels of an SPU. These are read-write
files that operate on a 32 bit word. Writing to one of these files
triggers an interrupt on the SPU. The value written to the signal
@@ -233,8 +232,7 @@ FILES
file.
- /signal1_type
- /signal2_type
+ /signal1_type, /signal2_type
These two files change the behavior of the signal1 and signal2 notifi-
cation files. The contain a numerical ASCII string which is read as
either "1" or "0". In mode 0 (overwrite), the hardware replaces the
@@ -259,18 +257,17 @@ FILES
the previous setting.
-EXAMPLES
+Examples
+========
/etc/fstab entry
none /spu spufs gid=spu 0 0
-AUTHORS
+Authors
+=======
Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>,
Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
-SEE ALSO
+See Also
+========
capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)
-
-
-
-Linux 2005-09-28 SPUFS(2)
diff --git a/MAINTAINERS b/MAINTAINERS
index ff9094b9310a..3b684c061677 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15938,7 +15938,7 @@ M: Jeremy Kerr <jk@ozlabs.org>
L: linuxppc-dev@lists.ozlabs.org
S: Supported
W: http://www.ibm.com/developerworks/power/cell/
-F: Documentation/filesystems/spufs.txt
+F: Documentation/filesystems/spufs/spufs.rst
F: arch/powerpc/platforms/cell/spufs/
SQUASHFS FILE SYSTEM
--
2.25.4
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v3 00/29] Convert files to ReST - part 2
2020-04-27 21:16 [PATCH v3 00/29] Convert files to ReST - part 2 Mauro Carvalho Chehab
2020-04-27 21:17 ` [PATCH v3 23/29] docs: filesystems: convert spufs/spufs.txt to ReST Mauro Carvalho Chehab
@ 2020-04-28 19:01 ` Jonathan Corbet
2020-04-28 19:25 ` Jan Harkes
2020-05-05 15:28 ` Jonathan Corbet
1 sibling, 2 replies; 5+ messages in thread
From: Jonathan Corbet @ 2020-04-28 19:01 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, linux-usb, linux-kernel, codalist,
linux-xfs, linux-cachefs, linux-fsdevel, linuxppc-dev
On Mon, 27 Apr 2020 23:16:52 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> This is the second part of a series I wrote sometime ago where I manually
> convert lots of files to be properly parsed by Sphinx as ReST files.
>
> As it touches on lot of stuff, this series is based on today's linux-next,
> at tag next-20190617.
>
> The first version of this series had 57 patches. The first part with 28 patches
> were already merged. Right now, there are still ~76 patches pending applying
> (including this series), and that's because I opted to do ~1 patch per converted
> directory.
>
> That sounds too much to be send on a single round. So, I'm opting to split
> it on 3 parts for the conversion, plus a final patch adding orphaned books
> to existing ones.
>
> Those patches should probably be good to be merged either by subsystem
> maintainers or via the docs tree.
So I'm happy to merge this set, but there is one thing that worries me a
bit...
> fs/cachefiles/Kconfig | 4 +-
> fs/coda/Kconfig | 2 +-
> fs/configfs/inode.c | 2 +-
> fs/configfs/item.c | 2 +-
> fs/fscache/Kconfig | 8 +-
> fs/fscache/cache.c | 8 +-
> fs/fscache/cookie.c | 2 +-
> fs/fscache/object.c | 4 +-
> fs/fscache/operation.c | 2 +-
> fs/locks.c | 2 +-
> include/linux/configfs.h | 2 +-
> include/linux/fs_context.h | 2 +-
> include/linux/fscache-cache.h | 4 +-
> include/linux/fscache.h | 42 +-
> include/linux/lsm_hooks.h | 2 +-
I'd feel a bit better if I could get an ack or two from filesystem folks
before I venture that far out of my own yard...what say you all?
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v3 00/29] Convert files to ReST - part 2
2020-04-28 19:01 ` [PATCH v3 00/29] Convert files to ReST - part 2 Jonathan Corbet
@ 2020-04-28 19:25 ` Jan Harkes
2020-05-05 15:28 ` Jonathan Corbet
1 sibling, 0 replies; 5+ messages in thread
From: Jan Harkes @ 2020-04-28 19:25 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-usb,
linux-kernel, linux-xfs, linux-cachefs, linux-fsdevel,
linuxppc-dev
On Tue, Apr 28, 2020 at 03:09:51PM -0400, Jonathan Corbet wrote:
> So I'm happy to merge this set, but there is one thing that worries me a
> bit...
>
> > fs/coda/Kconfig | 2 +-
>
> I'd feel a bit better if I could get an ack or two from filesystem folks
> before I venture that far out of my own yard...what say you all?
I acked the Coda parts on the first iteration of this patch. I have no
problem with you merging them.
Jan
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v3 00/29] Convert files to ReST - part 2
2020-04-28 19:01 ` [PATCH v3 00/29] Convert files to ReST - part 2 Jonathan Corbet
2020-04-28 19:25 ` Jan Harkes
@ 2020-05-05 15:28 ` Jonathan Corbet
1 sibling, 0 replies; 5+ messages in thread
From: Jonathan Corbet @ 2020-05-05 15:28 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, linux-usb, linux-kernel, codalist,
linux-xfs, linux-cachefs, linux-fsdevel, linuxppc-dev
On Tue, 28 Apr 2020 13:01:28 -0600
Jonathan Corbet <corbet@lwn.net> wrote:
> So I'm happy to merge this set, but there is one thing that worries me a
> bit...
>
> > fs/cachefiles/Kconfig | 4 +-
> > fs/coda/Kconfig | 2 +-
> > fs/configfs/inode.c | 2 +-
> > fs/configfs/item.c | 2 +-
> > fs/fscache/Kconfig | 8 +-
> > fs/fscache/cache.c | 8 +-
> > fs/fscache/cookie.c | 2 +-
> > fs/fscache/object.c | 4 +-
> > fs/fscache/operation.c | 2 +-
> > fs/locks.c | 2 +-
> > include/linux/configfs.h | 2 +-
> > include/linux/fs_context.h | 2 +-
> > include/linux/fscache-cache.h | 4 +-
> > include/linux/fscache.h | 42 +-
> > include/linux/lsm_hooks.h | 2 +-
>
> I'd feel a bit better if I could get an ack or two from filesystem folks
> before I venture that far out of my own yard...what say you all?
It's been another week and nobody has complained, so I'm taking that as
assent; the series has been applied.
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2020-05-05 15:35 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-04-27 21:16 [PATCH v3 00/29] Convert files to ReST - part 2 Mauro Carvalho Chehab
2020-04-27 21:17 ` [PATCH v3 23/29] docs: filesystems: convert spufs/spufs.txt to ReST Mauro Carvalho Chehab
2020-04-28 19:01 ` [PATCH v3 00/29] Convert files to ReST - part 2 Jonathan Corbet
2020-04-28 19:25 ` Jan Harkes
2020-05-05 15:28 ` Jonathan Corbet
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).