Messages in this thread | | | Subject | Re: [PATCH 0/3] Clean up crypto documentation | From | Joe Perches <> | Date | Mon, 24 Jun 2019 13:29:42 -0700 |
| |
On Mon, 2019-06-24 at 20:06 +0000, Gary R Hook wrote:
Hi Gary.
> On 6/24/19 2:30 PM, Joe Perches wrote: > > On Mon, 2019-06-24 at 19:07 +0000, Hook, Gary wrote: > > > Tidy up the crypto documentation by filling in some variable > > > descriptions, make some grammatical corrections, and enhance > > > formatting. > > > > While this seems generally OK, please try not to make the > > readability of the source _text_ less intelligible just > > to enhance the output formatting of the html. > > > > e.g.: > > > > Unnecessary blank lines separating function descriptions > > Removing space alignment from bullet point descriptions > > Apologies. I generally consider white space a Good Thing, > but will take your note and not do that. The blank lines I > added do not affect the output, so I should not have done > that. > > Also, I turned sentences into bulleted lists here, so I'm not > clear on whether that was a Bad Thing or not.
To me, using bulleted lists are not a bad thing at all but are quite the opposite for humans to read.
> Seems more legible > to me all the way around, but I clearly could be incorrect.
Not at all.
> I agree that mucking with alignment is a bad thing, and would not > intentionally do so. That said, if you would please elaborate on > any mistakes I've made? > > Finally, would you prefer a v2 of the patch set? Happy to do > whatever is preferred, of course.
Whatever Jonathan decides is fine with me. Mine was just a plea to avoid unnecessarily making the source text harder to read as that's what I mostly use.
I don't know if this extension is valid yet, but I believe just using <function_name>() is more readable as text than ``<function_name>`` or :c:func:`<function_name>`
https://lore.kernel.org/lkml/20190425200125.12302-1-corbet@lwn.net/T/
I prefer the automatic approach over the manual marking of functions as ideally sphinx formatting should not overly impact the source text.
| |