From 5fc68e1101d38c9ced4d07ef1526467618109de3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 4 Oct 2022 13:50:33 -0500 Subject: [PATCH] [DOC] Adding remarks about HTML and tables (#6485) * Adding remarks about HTML and tables --- doc/contributing/documentation_guide.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md index df67747710..6090928edf 100644 --- a/doc/contributing/documentation_guide.md +++ b/doc/contributing/documentation_guide.md @@ -151,6 +151,30 @@ We might consider whether to suppress when: - The same reference is repeated many times (e.g., _RDoc_ on this page). +### HTML Tags + +In general, avoid using HTML tags (even in formats where it's allowed) +because `ri` (the Ruby Interactive reference tool) +may not render them properly. + +### Tables + +Avoid building tables with HTML tags +(, etc.) + +Alternatives are: + +- The GFM (GitHub Flavored Markdown) table extension, + which is enabled by default. See + {GFM tables extension}[https://github.github.com/gfm/#tables-extension-]. + +- A {verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks], + using spaces and punctuation to format the text. + +Note that in neither case will +{text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup] +be honored. + ## Documenting Classes and Modules The general structure of the class or module documentation should be: