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=-5.6 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,USER_AGENT_SANE_2 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 2489FC433DF for ; Sun, 28 Jun 2020 08:40:29 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id C1ED0206F1 for ; Sun, 28 Jun 2020 08:40:28 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=kernel.org header.i=@kernel.org header.b="FBnzurYQ" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C1ED0206F1 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 34DEF6B0006; Sun, 28 Jun 2020 04:40:28 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 2DA3F6B0007; Sun, 28 Jun 2020 04:40:28 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 179ED6B0008; Sun, 28 Jun 2020 04:40:28 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0007.hostedemail.com [216.40.44.7]) by kanga.kvack.org (Postfix) with ESMTP id EF8B26B0006 for ; Sun, 28 Jun 2020 04:40:27 -0400 (EDT) Received: from smtpin04.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with ESMTP id 60ABD181AC9C6 for ; Sun, 28 Jun 2020 08:40:27 +0000 (UTC) X-FDA: 76977974094.04.boys97_48138d326e65 Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin04.hostedemail.com (Postfix) with ESMTP id 3F79280048EA for ; Sun, 28 Jun 2020 08:40:27 +0000 (UTC) X-HE-Tag: boys97_48138d326e65 X-Filterd-Recvd-Size: 8434 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by imf20.hostedemail.com (Postfix) with ESMTP for ; Sun, 28 Jun 2020 08:40:26 +0000 (UTC) Received: from coco.lan (ip5f5ad5c5.dynamic.kabel-deutschland.de [95.90.213.197]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 89DDA207E8; Sun, 28 Jun 2020 08:40:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1593333625; bh=sbpwUKMkAEYIjmKod52cizdsFab03jNLvQJZHLY8bFk=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=FBnzurYQ+gwV1a0CtnAvSAd1iAikjfnWyUUJ0hvrWCAgNm96qxD1598Yt8hvhZAFZ u5sSHiPU2BkPONdZrVaPiKeQiydNBb8vJfQMkX15xVC7xZ9KzOEc7vx7DPT4VrQ+/B hZf8iQY9mkzGUuy8vASkq789PDjKLtFDkdRdomA0= Date: Sun, 28 Jun 2020 10:40:11 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Linux Doc Mailing List , linux-kernel@vger.kernel.org, Vlastimil Babka , dri-devel@lists.freedesktop.org, "Steven Rostedt (VMware)" , "Aneesh Kumar K.V" , Arnd Bergmann , Alexandre Ghiti , Rob Herring , Pragat Pandya , "Joel Fernandes (Google)" , Mathieu Poirier , "Eric W. Biederman" , Phong Tran , Patrick Bellasi , Peter Zijlstra , Harald Seiler , David Airlie , Stephen Kitt , Ricardo =?UTF-8?B?Q2HDsXVlbG8=?= , Masami Hiramatsu , Masahiro Yamada , Daniel Jordan , Alexandre Belloni , Nitin Gupta , Peter Collingbourne , Sebastian Andrzej Siewior , linux-mm@kvack.org, Bartlomiej Zolnierkiewicz , "Frank A. Cancio Bello" , Johannes Weiner , Harry Wei , Thomas Gleixner , Andrew Morton , Stephen Boyd , Mike Leach , Maxime Ripard , Jonathan =?UTF-8?B?TmV1c2Now6RmZXI=?= , Alex Shi , "Matthew Wilcox (Oracle)" , Jason Gunthorpe , Masahiro Yamada , Krzysztof Kozlowski , Kees Cook , Sami Tolvanen , Maarten Lankhorst , Andy Shevchenko , Will Deacon , Thomas Zimmermann , devicetree@vger.kernel.org, Mike Rapoport , Daniel Vetter Subject: Re: [PATCH v3 0/7] Convert the remaining text files to ReST Message-ID: <20200628104011.7f7e8814@coco.lan> In-Reply-To: <20200626113459.413c3843@lwn.net> References: <20200626113459.413c3843@lwn.net> X-Mailer: Claws Mail 3.17.5 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 3F79280048EA X-Spamd-Result: default: False [0.00 / 100.00] X-Rspamd-Server: rspam02 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: Em Fri, 26 Jun 2020 11:34:59 -0600 Jonathan Corbet escreveu: > On Tue, 23 Jun 2020 15:31:33 +0200 > Mauro Carvalho Chehab wrote: >=20 > > The main goal of this series is to finish the ReST conversion. After th= is > > series, we have just those files still in plain old format: > >=20 > > - Documentation/RCU/RTFP.txt > > - Documentation/atomic_bitops.txt > > - Documentation/memory-barriers.txt > > - Documentation/atomic_t.txt > > - Documentation/filesystems/dax.txt > > - Documentation/filesystems/path-lookup.txt > > - Documentation/virt/kvm/devices/README =20 >=20 > OK, I've applied this set - glad to see the last one! Yeah! we can now focus on keeping it updated and re-organizing things, for the docs to look more like a real book. > Still *not* glad to see the LaTeX markup in the staging stuff; hopefully > we can do something about that soon. Agreed. The problem here is that, using the normal sized monospaced font, the maxim= um line width will be 67 columns[1]. The way Sphinx deals with mono-spaced texts is that it doesn't allow LaTeX to split lines. So, Sphinx sets LaTeX = to truncate long lines, forcing it to honor the line breaks generated by Sphin= x. At least newer versions of Sphinx have an optimization the LaTeX output code: on some cases Sphinx detect long lines and adds an artificial line break, preceded by a markup to indicate that the text would be otherwise truncated at the LaTeX output. Yet, if it is a single long word, it will just let it go past the margins and be truncated. For the files under staging, using this optimization will look really=20 weird, as the text output would be (with the enclosed path, meant to show the soft and hard line size limits)[2]: " 1 2 3 4 5 6 =E2=90= =A3 =E2=86=92 7 8 1234567890123456789012345678901234567890123456789012345678901234567890123= 4567890 =E2=86=92text here On atomic types (atomic_t atomic64_t and atomic_long_t). The atomic type provides an interface to the architecture's means=E2=90=A3 =E2=86=92 of atomic RMW operations between CPUs (atomic operations on MMIO are not=E2=90=A3 =E2=86=92 supported and can lead to fatal traps on some platforms)." What the LaTeX raw macro does is to use a smaller font that will allow=20 an 80-columns text to fit without those artificial breaks. I had to manually check what font size would work, and this might require=20 future changes, if Sphinx changes the default mono-spaced font or its default size. For the documents on staging, the solution is really simple from technical standpoint: just convert them to ReST. This would allow=20 Sphinx to use a proportional spaced font most of the time, which passes texts in paragraphs to LaTeX. This way, the line breaks=20 will be at the right places. I remember I tried doing it a few times, but there were strong=20 resistance. It could be possible to do some tricks at the conf.py to change some defaults, but anyone willing to do that will also need to=20 test the PDF output with all supported Sphinx versions, as the LaTeX output macros is not an stable API: we had to add several version-dependent stuff there, and even remove some features (like /resizebox for tables with many columns), as maintaining it was spending too much time and efforts. - [1] If you want to check, try building with the enclosed patch. [2] The output of the second line from the file shows some artifacts introduced:=20 - the word "some" disappeared, as it was truncated at the output; - the last "0" was half-truncated; - the symbol indicating that a conditional line would exist ("=E2=90=A3") was also truncated. Thanks, Mauro - diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index 0f1fdedf36bb..9488c35ec608 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -1,3 +1,5 @@ + 1 2 3 4 5 6 7 = 8 +12345678901234567890123456789012345678901234567890123456789012345678901234= 567890some text here =20 On atomic types (atomic_t atomic64_t and atomic_long_t). =20 diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.= rst index 184e6aece0a7..0c3acf27e1ff 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -19,17 +19,9 @@ Unsorted Documentation Atomic Types =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -.. raw:: latex - - \footnotesize - .. include:: ../atomic_t.txt :literal: =20 -.. raw:: latex - - \normalsize - Atomic bitops =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20