[DOC] Revision of Paragraphs section #1417
Conversation
BurdetteLamar
requested a deployment
to
fork-preview-protection
GitHub Actions
Waiting
| # A paragraph may contain only one type of nested block: | ||
| # | ||
| # - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]. | ||
| # - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]. | ||
| # - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]. | ||
| # - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists]. | ||
| # - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings]. | ||
| # - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]. | ||
| # - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]. |
There was a problem hiding this comment.
IMO a list with one bullet point shouldn't be a list.
I also don't know what the point of this change is, what is considered a "nested block"? The "Text Markup" section just talks about how to format the text with bold, italics, and monofont. Is that even considered a block or just formatting?
At any rate, I think we either keep the original (and maybe reword it) or just remove all of this completely.
There was a problem hiding this comment.
I've sometimes used a 1-item list to make treatments parallel, which I've thought helpful. (The other sections put nestings in lists.)
About your questions: I've asked them myself:
|
@peterzhu2118, might it be better to close this PR and instead explore the idea of demoting text markup from its status as a block? |
Maybe? I'm not sure how we want to define what a block is. |
Although technically it's possible to nest some types of blocks in a paragraph (by eschewing newlines), it's poor practice. Is the language here too strong? Or should there be explanation and warnings?