From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-12.1 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING,SIGNED_OFF_BY,SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 882C0C10F11 for ; Wed, 24 Apr 2019 12:45:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 3F0A3218B0 for ; Wed, 24 Apr 2019 12:45:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1556109904; bh=zZ6vmOirLx48ku8W7mIjPOHjyn5ThyAl1YJUO+UsVbU=; h=Date:From:To:Cc:Subject:In-Reply-To:References:List-ID:From; b=vkSApaIBCDpO45zcRrj17pVcZciSSJsw+eHIu/CbJe095FthrGjCq1Kct7UoMHj8u 6OI785vcfKcXurfXpCaDNxBsIfwFA2d+P63sQrB6+KZj+kAtuuV0B0975CXwkxsdak IdDr00USi02fmKUxInvUMPOcjlFINUvtKEeGY0dw= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730247AbfDXMpD (ORCPT ); Wed, 24 Apr 2019 08:45:03 -0400 Received: from casper.infradead.org ([85.118.1.10]:34228 "EHLO casper.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726167AbfDXMpD (ORCPT ); Wed, 24 Apr 2019 08:45:03 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=Content-Transfer-Encoding:Content-Type: MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To:From:Date:Sender :Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=R5SiLqa2L2lElHSYH0cIVkCF0zE6ll1IFGpxCMe6jcI=; b=AyNobqD4Lf5TYGyT9rTtDfxyQn NgIhWDm7I17BKD/hEefWZCIw3XzlsutVPS6Kvpd6SlL4lzIfs+NWgYWoJdhEoRawdmm0wQLgOI5O4 Q4hOT8hXfMKa1SXxAigQIKZka6bx9ofnZpb+nfilqlHg6bBm2OiW7XcCUaQ2bpeREXStTBIhOn40C DzFYKq5X6lubCGr0J0segcdXnsYVjQjndtrASQOpZwtL3+oU8CC5kah+/gFT2C6coOka2tBU3QZ4A R9ILdvoIc7OBpb5zWx/ng/h1HdIbKJoQSh+TS3C115bg9StTHtd8LJzb1OA5rQ9kNdI/Dn0QbYrrn hAQq8DvQ==; Received: from 177.17.136.231.dynamic.adsl.gvt.net.br ([177.17.136.231] helo=coco.lan) by casper.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hJHGj-0003DA-Kx; Wed, 24 Apr 2019 12:44:58 +0000 Date: Wed, 24 Apr 2019 09:44:50 -0300 From: Mauro Carvalho Chehab To: Cornelia Huck Cc: Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Martin Schwidefsky , Heiko Carstens , Tony Krowiak , Pierre Morel , Halil Pasic , Farhan Ali , Eric Farman , linux-s390@vger.kernel.org, kvm@vger.kernel.org Subject: Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst Message-ID: <20190424094450.1e3da646@coco.lan> In-Reply-To: <20190424134109.2891a7cc.cohuck@redhat.com> References: <20190424134109.2891a7cc.cohuck@redhat.com> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Wed, 24 Apr 2019 13:41:09 +0200 Cornelia Huck escreveu: > On Mon, 22 Apr 2019 10:27:20 -0300 > Mauro Carvalho Chehab wrote: > > > Convert all text files with s390 documentation to ReST format. > > > > Tried to preserve as much as possible the original document > > format. Still, some of the files required some work in order > > for it to be visible on both plain text and after converted > > to html. > > > > The conversion is actually: > > - add blank lines and identation in order to identify paragraphs; > > - fix tables markups; > > - add some lists markups; > > - mark literal blocks; > > - adjust title markups. > > > > At its new index.rst, let's add a :orphan: while this is not linked to > > the main index.rst file, in order to avoid build warnings. > > > > Signed-off-by: Mauro Carvalho Chehab > > --- > > .../admin-guide/kernel-parameters.txt | 4 +- > > Documentation/driver-api/s390-drivers.rst | 4 +- > > Documentation/s390/{3270.txt => 3270.rst} | 85 +- > > Documentation/s390/{cds.txt => cds.rst} | 354 ++- > > .../s390/{CommonIO => common_io.rst} | 49 +- > > Documentation/s390/{DASD => dasd.rst} | 33 +- > > .../{Debugging390.txt => debugging390.rst} | 2389 ++++++++++------- > > .../{driver-model.txt => driver-model.rst} | 179 +- > > Documentation/s390/index.rst | 30 + > > .../s390/{monreader.txt => monreader.rst} | 85 +- > > Documentation/s390/{qeth.txt => qeth.rst} | 36 +- > > Documentation/s390/s390dbf.rst | 803 ++++++ > > Documentation/s390/s390dbf.txt | 667 ----- > > Documentation/s390/text_files.rst | 11 + > > .../s390/{vfio-ap.txt => vfio-ap.rst} | 487 ++-- > > .../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +- > > .../s390/{zfcpdump.txt => zfcpdump.rst} | 2 + > > MAINTAINERS | 4 +- > > arch/s390/Kconfig | 4 +- > > arch/s390/include/asm/debug.h | 4 +- > > drivers/s390/char/zcore.c | 2 +- > > 21 files changed, 3089 insertions(+), 2233 deletions(-) > > rename Documentation/s390/{3270.txt => 3270.rst} (90%) > > rename Documentation/s390/{cds.txt => cds.rst} (64%) > > rename Documentation/s390/{CommonIO => common_io.rst} (87%) > > rename Documentation/s390/{DASD => dasd.rst} (92%) > > rename Documentation/s390/{Debugging390.txt => debugging390.rst} (53%) > > rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%) > > create mode 100644 Documentation/s390/index.rst > > rename Documentation/s390/{monreader.txt => monreader.rst} (81%) > > rename Documentation/s390/{qeth.txt => qeth.rst} (62%) > > create mode 100644 Documentation/s390/s390dbf.rst > > delete mode 100644 Documentation/s390/s390dbf.txt > > create mode 100644 Documentation/s390/text_files.rst > > rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%) > > rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%) > > rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%) > > > > (...) > > > diff --git a/Documentation/s390/3270.txt b/Documentation/s390/3270.rst > > similarity index 90% > > rename from Documentation/s390/3270.txt > > rename to Documentation/s390/3270.rst > > index 7c715de99774..e09e77954238 100644 > > --- a/Documentation/s390/3270.txt > > +++ b/Documentation/s390/3270.rst > > (...) > > > @@ -17,12 +21,12 @@ twenty and thirty years ago. > > You may have 3270s in-house and not know it. If you're using the > > VM-ESA operating system, define a 3270 to your virtual machine by using > > the command "DEF GRAF " This paper presumes you will be > > -defining four 3270s with the CP/CMS commands > > +defining four 3270s with the CP/CMS commands: > > > > - DEF GRAF 620 > > - DEF GRAF 621 > > - DEF GRAF 622 > > - DEF GRAF 623 > > + - DEF GRAF 620 > > + - DEF GRAF 621 > > + - DEF GRAF 622 > > + - DEF GRAF 623 > > IIUC, this makes this into a bulleted list... but the user is supposed > to enter these commands (similar to the shell commands further down in > this file). Ah, OK! I'll change it to use a literal block (::). > > > > > Your network connection from VM-ESA allows you to use x3270, tn3270, or > > another 3270 emulator, started from an xterm window on your PC or > > (...) > > > @@ -84,20 +92,22 @@ Here are the installation steps in detail: > > make modules_install > > > > 2. (Perform this step only if you have configured tub3270 as a > > - module.) Add a line to a file /etc/modprobe.d/*.conf to automatically > > + module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically > > load the driver when it's needed. With this line added, you will see > > login prompts appear on your 3270s as soon as boot is complete (or > > with emulated 3270s, as soon as you dial into your vm guest using the > > command "DIAL "). Since the line-mode major number is > > - 227, the line to add should be: > > + 227, the line to add should be:: > > + > > alias char-major-227 tub3270 > > > > 3. Define graphic devices to your vm guest machine, if you > > haven't already. Define them before you reboot (reipl): > > - DEFINE GRAF 620 > > - DEFINE GRAF 621 > > - DEFINE GRAF 622 > > - DEFINE GRAF 623 > > + > > + - DEFINE GRAF 620 > > + - DEFINE GRAF 621 > > + - DEFINE GRAF 622 > > + - DEFINE GRAF 623 > > Same here. Ok. > > > > > 4. Reboot. The reboot process scans hardware devices, including > > 3270s, and this enables the tub3270 driver once loaded to respond > > (...) > > > > diff --git a/Documentation/s390/CommonIO b/Documentation/s390/common_io.rst > > similarity index 87% > > rename from Documentation/s390/CommonIO > > rename to Documentation/s390/common_io.rst > > index 6e0f63f343b4..846485681ce7 100644 > > --- a/Documentation/s390/CommonIO > > +++ b/Documentation/s390/common_io.rst > > @@ -1,5 +1,9 @@ > > -S/390 common I/O-Layer - command line parameters, procfs and debugfs entries > > -============================================================================ > > +====================== > > +S/390 common I/O-Layer > > +====================== > > + > > +command line parameters, procfs and debugfs entries > > +=================================================== > > I don't see why this should be split into two lines? If anything needs > to be changed, I'd drop the hyphen. No real need for html output. I suspect that a big title like the above would cause troubles for pdf output. That's basically why I opted to break it. Yet, if you prefer, I'll keep it as-is. > > > > > Command line parameters > > ----------------------- > > @@ -13,7 +17,7 @@ Command line parameters > > device := {all | [!]ipldev | [!]condev | [!] | [!]-} > > > > The given devices will be ignored by the common I/O-layer; no detection > > - and device sensing will be done on any of those devices. The subchannel to > > + and device sensing will be done on any of those devices. The subchannel to > > which the device in question is attached will be treated as if no device was > > attached. > > > > @@ -28,14 +32,20 @@ Command line parameters > > keywords can be used to refer to the CCW based boot device and CCW console > > device respectively (these are probably useful only when combined with the '!' > > operator). The '!' operator will cause the I/O-layer to _not_ ignore a device. > > - The command line is parsed from left to right. > > + The command line > > + is parsed from left to right. > > Why this change? This was unintentional. I probably hit by mistake on that line. I'll revert. > > > + > > + For example:: > > > > - For example, > > cio_ignore=0.0.0023-0.0.0042,0.0.4711 > > + > > will ignore all devices ranging from 0.0.0023 to 0.0.0042 and the device > > 0.0.4711, if detected. > > - As another example, > > + > > + As another example:: > > + > > cio_ignore=all,!0.0.4711,!0.0.fd00-0.0.fd02 > > + > > will ignore all devices but 0.0.4711, 0.0.fd00, 0.0.fd01, 0.0.fd02. > > > > By default, no devices are ignored. > > (...) > > > diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/debugging390.rst > > similarity index 53% > > rename from Documentation/s390/Debugging390.txt > > rename to Documentation/s390/debugging390.rst > > index c35804c238ad..d49305fd5e1a 100644 > > --- a/Documentation/s390/Debugging390.txt > > +++ b/Documentation/s390/debugging390.rst > > I'll skip this one... > > (Question for the s390 arch maintainers: I remember that there was some > interesting stuff in there, but I'm not sure how much of it is still > accurate/useful... is it worth spending time on trying to update this?) > > (...) > > > > diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst > > new file mode 100644 > > index 000000000000..ec2a1faa414b > > --- /dev/null > > +++ b/Documentation/s390/s390dbf.rst > > (...) > > > diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt > > deleted file mode 100644 > > index 61329fd62e89..000000000000 > > --- a/Documentation/s390/s390dbf.txt > > +++ /dev/null > > I wonder why this does not show up as a rename? Probably because the number of changes were bigger than 50%. The algo there seems to be dumb. I suspect that adding whitespace/tabs on lines makes it to consider the entire line as different. git log -M10 would change the threshold to 10% similarity and will likely show it as a rename. I'll use -M on the next version for this patch. > > (...) > > > diff --git a/Documentation/s390/text_files.rst b/Documentation/s390/text_files.rst > > new file mode 100644 > > index 000000000000..c94d05d4fa17 > > --- /dev/null > > +++ b/Documentation/s390/text_files.rst > > @@ -0,0 +1,11 @@ > > +ibm 3270 changelog > > +------------------ > > + > > +.. include:: 3270.ChangeLog > > + :literal: > > + > > +ibm 3270 config3270.sh > > +---------------------- > > + > > +.. literalinclude:: config3270.sh > > + :language: shell > > > Another question for the s390 arch maintainers: How valuable is this still? > > (...) > > > diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.rst > > similarity index 89% > > rename from Documentation/s390/vfio-ccw.txt > > rename to Documentation/s390/vfio-ccw.rst > > index 2be11ad864ff..1f6d0b56d53e 100644 > > --- a/Documentation/s390/vfio-ccw.txt > > +++ b/Documentation/s390/vfio-ccw.rst > > (...) > > > @@ -295,6 +321,6 @@ Reference > > 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) > > 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204) > > 3. https://en.wikipedia.org/wiki/Channel_I/O > > -4. Documentation/s390/cds.txt > > +4. Documentation/s390/cds.rst > > 5. Documentation/vfio.txt > > 6. Documentation/vfio-mediated-device.txt > > Are these two renamed in a later patch? Yes. Patch 56 renames almost all Documentation/*.txt to .rst. Those files are already parsed properly by Sphinx, so no changes there are needed. I'm working on followup patches (not submitted yet), with moves all ReST files under Documentation to some place. In the specific case of those files, on the series I'm working, I moved them to be part of the driver-api: https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames&id=3387ab063cf43f91d5c0f79d741244e7dbcdec05 The results, when parsed, are at: https://www.infradead.org/~mchehab/rst_conversion/driver-api/vfio.html https://www.infradead.org/~mchehab/rst_conversion/driver-api/vfio-mediated-device.html Thanks, Mauro