* [PATCH 0/1] docs: fix kernel-driver-statement rendering
@ 2020-10-05 13:02 Gaëtan Harter
2020-10-05 13:02 ` [PATCH 1/1] " Gaëtan Harter
0 siblings, 1 reply; 5+ messages in thread
From: Gaëtan Harter @ 2020-10-05 13:02 UTC (permalink / raw
To: linux-doc, corbet, federico.vaga, harryxiyou; +Cc: Gaëtan Harter
Dear Documentation maintainers,
while browsing the "Kernel driver statement" page on kernel.org [1],
I noticed the name list was split after "J. Bruce Fields" with some extra line
spacing.
The rendered html source shows that the `J.` is interpreted as list item in
`ReST` syntax.
I propose a patch to remove this rendering issue with an escape string
before to still allow doing `git grep` for the name.
I still adds rst only clutters the text though.
I checked the rendered HTML and PDF for both the English and translated
versions to verify it was fixed.
On my local runs the HTML had extra `<p>` tags compared to the webpage so
not sure what was different in the environment.
I found other pages having the same type of issues by grepping the output
for "upperalpha" and checking the inappropriate occurrences.
If it is a class of fixes that is wanted, I could propose other patchsets with
a batch of them.
It may be a good thing to then add the information to a general how to write
documentation document to try preventing it from reappearing.
I would wait for feedback before doing these.
Please keep me in CC as I am not registered on the list.
1: https://www.kernel.org/doc/html/v5.8/process/kernel-driver-statement.html
Best Regards,
Gaëtan Harter
Gaëtan Harter (1):
docs: fix kernel-driver-statement rendering
Documentation/process/kernel-driver-statement.rst | 2 +-
.../translations/it_IT/process/kernel-driver-statement.rst | 2 +-
.../translations/zh_CN/process/kernel-driver-statement.rst | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
base-commit: 9f35cf8bd7e3347b0679c3f9b5e0bc5493925a1f
--
2.28.0
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH 1/1] docs: fix kernel-driver-statement rendering
2020-10-05 13:02 [PATCH 0/1] docs: fix kernel-driver-statement rendering Gaëtan Harter
@ 2020-10-05 13:02 ` Gaëtan Harter
2020-10-05 15:37 ` Jonathan Corbet
0 siblings, 1 reply; 5+ messages in thread
From: Gaëtan Harter @ 2020-10-05 13:02 UTC (permalink / raw
To: linux-doc, corbet, federico.vaga, harryxiyou; +Cc: Gaëtan Harter
Remove the extra newline and indentation after `J. Bruce Fields` in the
rendered html, and extra indentation in the rendered pdf.
The `J.` sequence was interpreted by sphinx as a letter ordered list
starting at letter `J`. It produced a sub ordered list as item of the
main item list.
<li><ol class="first upperalpha" start="10">
<li>Bruce Fields</li>
</ol>
</li>
The escaping is done before the name and not between the `J` and `.` to
keep the name writing intact.
Signed-off-by: Gaëtan Harter <hartergaetan@gmail.com>
---
Documentation/process/kernel-driver-statement.rst | 2 +-
.../translations/it_IT/process/kernel-driver-statement.rst | 2 +-
.../translations/zh_CN/process/kernel-driver-statement.rst | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst
index a849790a68bc..3a89fec1882e 100644
--- a/Documentation/process/kernel-driver-statement.rst
+++ b/Documentation/process/kernel-driver-statement.rst
@@ -67,7 +67,7 @@ today, have in the past, or will in the future.
- Pekka Enberg
- Jan Engelhardt
- Mark Fasheh
- - J. Bruce Fields
+ - \ J. Bruce Fields
- Larry Finger
- Jeremy Fitzhardinge
- Mike Frysinger
diff --git a/Documentation/translations/it_IT/process/kernel-driver-statement.rst b/Documentation/translations/it_IT/process/kernel-driver-statement.rst
index f016a75a9d6e..2b4acc95c347 100644
--- a/Documentation/translations/it_IT/process/kernel-driver-statement.rst
+++ b/Documentation/translations/it_IT/process/kernel-driver-statement.rst
@@ -75,7 +75,7 @@ futuro.
- Pekka Enberg
- Jan Engelhardt
- Mark Fasheh
- - J. Bruce Fields
+ - \ J. Bruce Fields
- Larry Finger
- Jeremy Fitzhardinge
- Mike Frysinger
diff --git a/Documentation/translations/zh_CN/process/kernel-driver-statement.rst b/Documentation/translations/zh_CN/process/kernel-driver-statement.rst
index 2b3375bcccfd..a7fac3f04bb1 100644
--- a/Documentation/translations/zh_CN/process/kernel-driver-statement.rst
+++ b/Documentation/translations/zh_CN/process/kernel-driver-statement.rst
@@ -64,7 +64,7 @@
- Pekka Enberg
- Jan Engelhardt
- Mark Fasheh
- - J. Bruce Fields
+ - \ J. Bruce Fields
- Larry Finger
- Jeremy Fitzhardinge
- Mike Frysinger
--
2.28.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 1/1] docs: fix kernel-driver-statement rendering
2020-10-05 13:02 ` [PATCH 1/1] " Gaëtan Harter
@ 2020-10-05 15:37 ` Jonathan Corbet
2020-10-06 7:34 ` Federico Vaga
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2020-10-05 15:37 UTC (permalink / raw
To: Gaëtan Harter; +Cc: linux-doc, federico.vaga, harryxiyou
On Mon, 5 Oct 2020 15:02:13 +0200
Gaëtan Harter <hartergaetan@gmail.com> wrote:
> Remove the extra newline and indentation after `J. Bruce Fields` in the
> rendered html, and extra indentation in the rendered pdf.
>
> The `J.` sequence was interpreted by sphinx as a letter ordered list
> starting at letter `J`. It produced a sub ordered list as item of the
> main item list.
>
> <li><ol class="first upperalpha" start="10">
> <li>Bruce Fields</li>
> </ol>
> </li>
>
> The escaping is done before the name and not between the `J` and `.` to
> keep the name writing intact.
>
> Signed-off-by: Gaëtan Harter <hartergaetan@gmail.com>
> ---
> Documentation/process/kernel-driver-statement.rst | 2 +-
> .../translations/it_IT/process/kernel-driver-statement.rst | 2 +-
> .../translations/zh_CN/process/kernel-driver-statement.rst | 2 +-
> 3 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst
> index a849790a68bc..3a89fec1882e 100644
> --- a/Documentation/process/kernel-driver-statement.rst
> +++ b/Documentation/process/kernel-driver-statement.rst
> @@ -67,7 +67,7 @@ today, have in the past, or will in the future.
> - Pekka Enberg
> - Jan Engelhardt
> - Mark Fasheh
> - - J. Bruce Fields
> + - \ J. Bruce Fields
> - Larry Finger
Thanks for figuring this out and explaining it so well. This is a sad
ambiguity in the RST syntax, I guess.
In this case, though, I'm not convinced that the cure isn't worse than the
disease. We've traded a blank line in the HTML output for some ugly
markup in the original text; I'm not sure we want to do that.
For this particular file, perhaps the best solution is just to put the
list of signatures into a literal block. The fix for other occurrences
may be different.
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 1/1] docs: fix kernel-driver-statement rendering
2020-10-05 15:37 ` Jonathan Corbet
@ 2020-10-06 7:34 ` Federico Vaga
2020-10-08 17:12 ` Gaëtan Harter
0 siblings, 1 reply; 5+ messages in thread
From: Federico Vaga @ 2020-10-06 7:34 UTC (permalink / raw
To: Jonathan Corbet; +Cc: Gaëtan Harter, linux-doc, harryxiyou
Without implementing any hack, can't we put the full name? Or just
remove "J." :)
On 2020-10-05 17:37, Jonathan Corbet wrote:
> On Mon, 5 Oct 2020 15:02:13 +0200
> Gaëtan Harter <hartergaetan@gmail.com> wrote:
>
>> Remove the extra newline and indentation after `J. Bruce Fields` in
>> the
>> rendered html, and extra indentation in the rendered pdf.
>>
>> The `J.` sequence was interpreted by sphinx as a letter ordered list
>> starting at letter `J`. It produced a sub ordered list as item of the
>> main item list.
>>
>> <li><ol class="first upperalpha" start="10">
>> <li>Bruce Fields</li>
>> </ol>
>> </li>
>>
>> The escaping is done before the name and not between the `J` and `.`
>> to
>> keep the name writing intact.
>>
>> Signed-off-by: Gaëtan Harter <hartergaetan@gmail.com>
>> ---
>> Documentation/process/kernel-driver-statement.rst | 2
>> +-
>> .../translations/it_IT/process/kernel-driver-statement.rst | 2
>> +-
>> .../translations/zh_CN/process/kernel-driver-statement.rst | 2
>> +-
>> 3 files changed, 3 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/process/kernel-driver-statement.rst
>> b/Documentation/process/kernel-driver-statement.rst
>> index a849790a68bc..3a89fec1882e 100644
>> --- a/Documentation/process/kernel-driver-statement.rst
>> +++ b/Documentation/process/kernel-driver-statement.rst
>> @@ -67,7 +67,7 @@ today, have in the past, or will in the future.
>> - Pekka Enberg
>> - Jan Engelhardt
>> - Mark Fasheh
>> - - J. Bruce Fields
>> + - \ J. Bruce Fields
>> - Larry Finger
>
> Thanks for figuring this out and explaining it so well. This is a sad
> ambiguity in the RST syntax, I guess.
>
> In this case, though, I'm not convinced that the cure isn't worse than
> the
> disease. We've traded a blank line in the HTML output for some ugly
> markup in the original text; I'm not sure we want to do that.
>
> For this particular file, perhaps the best solution is just to put the
> list of signatures into a literal block. The fix for other occurrences
> may be different.
>
> Thanks,
>
> jon
--
Federico Vaga
http://www.federicovaga.it/
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 1/1] docs: fix kernel-driver-statement rendering
2020-10-06 7:34 ` Federico Vaga
@ 2020-10-08 17:12 ` Gaëtan Harter
0 siblings, 0 replies; 5+ messages in thread
From: Gaëtan Harter @ 2020-10-08 17:12 UTC (permalink / raw
To: Federico Vaga, Jonathan Corbet; +Cc: linux-doc, harryxiyou
On 10/6/20 9:34 AM, Federico Vaga wrote:
> Without implementing any hack, can't we put the full name? Or just remove "J." :)
I would not dare myself to change the names just as an outsider.
If there is a positive feedback for this one, I could de the change.
I currently only identified 5 other places where this currently applies [1]
so would be a reasonable task to do.
>
> On 2020-10-05 17:37, Jonathan Corbet wrote:
>> On Mon, 5 Oct 2020 15:02:13 +0200
>> Gaëtan Harter <hartergaetan@gmail.com> wrote:
>>
>>> Remove the extra newline and indentation after `J. Bruce Fields` in the
>>> rendered html, and extra indentation in the rendered pdf.
>>>
>>> The `J.` sequence was interpreted by sphinx as a letter ordered list
>>> starting at letter `J`. It produced a sub ordered list as item of the
>>> main item list.
>>>
>>> <li><ol class="first upperalpha" start="10">
>>> <li>Bruce Fields</li>
>>> </ol>
>>> </li>
>>>
>>> The escaping is done before the name and not between the `J` and `.` to
>>> keep the name writing intact.
>>>
>>> Signed-off-by: Gaëtan Harter <hartergaetan@gmail.com>
>>> ---
>>> Documentation/process/kernel-driver-statement.rst | 2 +-
>>> .../translations/it_IT/process/kernel-driver-statement.rst | 2 +-
>>> .../translations/zh_CN/process/kernel-driver-statement.rst | 2 +-
>>> 3 files changed, 3 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst
>>> index a849790a68bc..3a89fec1882e 100644
>>> --- a/Documentation/process/kernel-driver-statement.rst
>>> +++ b/Documentation/process/kernel-driver-statement.rst
>>> @@ -67,7 +67,7 @@ today, have in the past, or will in the future.
>>> - Pekka Enberg
>>> - Jan Engelhardt
>>> - Mark Fasheh
>>> - - J. Bruce Fields
>>> + - \ J. Bruce Fields
>>> - Larry Finger
>>
>> Thanks for figuring this out and explaining it so well. This is a sad
>> ambiguity in the RST syntax, I guess.
>>
>> In this case, though, I'm not convinced that the cure isn't worse than the
>> disease. We've traded a blank line in the HTML output for some ugly
>> markup in the original text; I'm not sure we want to do that.
As mentioned in my email I also had doubts about it.
I checked and saw the escape character used in some other files, for example
`Documentation/cdrom/cdrom-standard.rst` where it was in the middle of the text.
Being somehow a political decision what was more important between the source and
the rendered output. So thought it was worth proposing at least.
For this one it seemed not too too bad being in front only, but for ones with
several parts it is quite ugly like in `userspace-api/media/dvb/dvbapi.rst` see [1].
Unfortunately there is no "verbatim" mode that is not displayed as code.
>>
>> For this particular file, perhaps the best solution is just to put the
>> list of signatures into a literal block. The fix for other occurrences
>> may be different.
>>
I did an analysis of the other `upperalpha` occurrences [2].
I excluded the ones that are of different types. I can propose separate patches for them.
This would currently leave only the following 5 cases with the same reason due to name shortening.
As it checks the html, it only finds the documents converted to `rst` I think.
I did use the same fix to make them visible.
Most of them would not work with a literal block I think as being as would constrain more things.
Putting the full name as suggested by Federico could solve them.
Would you agree with this kind of solution?
Best Regards,
Gaëtan
1:
diff --git a/Documentation/PCI/pcieaer-howto.rst b/Documentation/PCI/pcieaer-howto.rst
index 0b36b9ebfa4b..4eb62b8aacd0 100644
--- a/Documentation/PCI/pcieaer-howto.rst
+++ b/Documentation/PCI/pcieaer-howto.rst
@@ -5,7 +5,7 @@
The PCI Express Advanced Error Reporting Driver Guide HOWTO
===========================================================
-:Authors: - T. Long Nguyen <tom.l.nguyen@intel.com>
+:Authors: - \ T. Long Nguyen <tom.l.nguyen@intel.com>
- Yanmin Zhang <yanmin.zhang@intel.com>
:Copyright: |copy| 2006 Intel Corporation
diff --git a/Documentation/ia64/efirtc.rst b/Documentation/ia64/efirtc.rst
index fd8328408301..46985b7ec6f5 100644
--- a/Documentation/ia64/efirtc.rst
+++ b/Documentation/ia64/efirtc.rst
@@ -2,7 +2,7 @@
EFI Real Time Clock driver
==========================
-S. Eranian <eranian@hpl.hp.com>
+\ S. Eranian <eranian@hpl.hp.com>
March 2000
diff --git a/Documentation/scsi/scsi-changer.rst b/Documentation/scsi/scsi-changer.rst
index ab60e7e61a6c..0edd72ec0bec 100644
--- a/Documentation/scsi/scsi-changer.rst
+++ b/Documentation/scsi/scsi-changer.rst
@@ -167,7 +167,7 @@ method. With (more or less) help from:
- Daniel Moehwald <moehwald@hdg.de>
- Dane Jasper <dane@sonic.net>
- - R. Scott Bailey <sbailey@dsddi.eds.com>
+ - \ R. Scott Bailey <sbailey@dsddi.eds.com>
- Jonathan Corbet <corbet@lwn.net>
Special thanks go to
diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst
index 74b16ab3fd94..ed38f25093ff 100644
--- a/Documentation/userspace-api/media/dvb/dvbapi.rst
+++ b/Documentation/userspace-api/media/dvb/dvbapi.rst
@@ -61,11 +61,11 @@ Revision and Copyright
Authors:
-- J. K. Metzler, Ralph <rjkm@metzlerbros.de>
+- \ J.\ K. Metzler, Ralph <rjkm@metzlerbros.de>
- Original author of the Digital TV API documentation.
-- O. C. Metzler, Marcus <rjkm@metzlerbros.de>
+- \ O.\ C. Metzler, Marcus <rjkm@metzlerbros.de>
- Original author of the Digital TV API documentation.
diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst
index 3c9634173e82..29d11be791fe 100644
--- a/Documentation/userspace-api/media/v4l/biblio.rst
+++ b/Documentation/userspace-api/media/v4l/biblio.rst
@@ -413,4 +413,4 @@ VP8
:title: RFC 6386: "VP8 Data Format and Decoding Guide"
-:author: J. Bankoski et al.
+:author: \ J. Bankoski et al.
2:
grep --color=auto -Inr \
-C 1 \
-e "upperalpha" \
--exclude-dir=_static \
\
$(: This ones should be fixed, they must be titles) \
--exclude=fbcon.html \
\
$(: Copyright symbol \(C\), replace by |copy|) \
--exclude=basic-pm-debugging.html \
--exclude=c2port.html \
--exclude=charger-manager.html \
--exclude=drivers-testing.html \
--exclude=freezing-of-tasks.html \
--exclude=opp.html \
--exclude=overview.html \
--exclude=runtime_pm.html \
--exclude=suspend-and-cpuhotplug.html \
--exclude=swsusp-and-swap-files.html \
--exclude=tlan.html \
--exclude=userland-swsusp.html \
\
$(: Should be interpreted as list items but not all are) \
--exclude=3270.html \
--exclude=rpc-server-gss.html \
\
$(: Q/A may not be a list item? or could just stay anyway) \
--exclude=stat.html \
\
$(: These seems to be legitimate uses) \
--exclude=acpi-lid.html \
--exclude=arcmsr_spec.html \
--exclude=bcache.html \
--exclude=dpio-driver.html \
--exclude=drm-kms-helpers.html \
--exclude=dscr.html \
--exclude=fuse.html \
--exclude=linuxized-acpica.htm \
--exclude=linuxized-acpica.html \
--exclude=memory-hotplug.html \
--exclude=mmu_notifier.html \
--exclude=resctrl_ui.html \
--exclude=sentelic.html \
--exclude=sharedsubtree.html \
\
Documentation/output/
>> Thanks,
>>
>> jon
>
^ permalink raw reply related [flat|nested] 5+ messages in thread
end of thread, other threads:[~2020-10-08 17:12 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-10-05 13:02 [PATCH 0/1] docs: fix kernel-driver-statement rendering Gaëtan Harter
2020-10-05 13:02 ` [PATCH 1/1] " Gaëtan Harter
2020-10-05 15:37 ` Jonathan Corbet
2020-10-06 7:34 ` Federico Vaga
2020-10-08 17:12 ` Gaëtan Harter
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.