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@xxxxxxxxx> 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@xxxxxxxxx>
>>> ---
>>> 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@xxxxxxxxx>
+:Authors: - \ T. Long Nguyen <tom.l.nguyen@xxxxxxxxx>
- Yanmin Zhang <yanmin.zhang@xxxxxxxxx>
: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@xxxxxxxxxx>
+\ S. Eranian <eranian@xxxxxxxxxx>
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@xxxxxx>
- Dane Jasper <dane@xxxxxxxxx>
- - R. Scott Bailey <sbailey@xxxxxxxxxxxxx>
+ - \ R. Scott Bailey <sbailey@xxxxxxxxxxxxx>
- Jonathan Corbet <corbet@xxxxxxx>
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@xxxxxxxxxxxxxx>
+- \ J.\ K. Metzler, Ralph <rjkm@xxxxxxxxxxxxxx>
- Original author of the Digital TV API documentation.
-- O. C. Metzler, Marcus <rjkm@xxxxxxxxxxxxxx>
+- \ O.\ C. Metzler, Marcus <rjkm@xxxxxxxxxxxxxx>
- 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
>
