BUGS/NOTE/ETC. presentation

[abathur]

Some docs have a section titled BUGS or NOTE (here's an example: https://github.com/ldmud/ldmud/blob/master/doc/efun/net_connect#L36, note that BUG, REMARKS, NOTES, WARNING, TIPS, LIMITATIONS, and MISCELLANEOUS are all also in use for similar purposes). In other cases, we have paragraphs mixed into the primary concept/function/etc. description (here's an example: https://github.com/ldmud/ldmud/blob/master/doc/efun/first_inventory#L29) which might say "Note: this frobulates the wombats." or "Warning: This fails if the wombats have already been frobulated." It would be nice to collapse this diversity into a minimal number of standard practices. The easiest* choices are probably:

1. Mark-up each bug/warning/note/tip separately.
   • sphinx/docutils support several directives for providing what they call admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition" which can be used to mark up each one individually; we can add our own where we want a semantic theirs lackIn the HTML these get wrapped with a specially formatted box which nicely calls attention to them: http://abathur.github.io/ldmud-doc/build/html/efun/first_inventory.html
2. Provide sections for notes/bugs/warnings/tips/hints and use a bulleted list to enumerate each.

I favor marking them up separately because it has good semantics and encourages us to place them closest to related concepts in the flow of the documentation, instead of lazily cobbling a de-contextualized list together at the end. One of the stronger reasons not to do it that way is probably that they don't stand out as well in the plaintext without their own section (though I wonder how useful they are out of context).

For reference, here's the source and plaintext version of first_inventory used above (ignore some of the wonky whitespace issues in the Warning itself; those are just issues that need to be ironed out): https://raw.githubusercontent.com/abathur/ldmud-doc/master/source/efun/first_inventory.rst https://github.com/abathur/ldmud-doc/blob/master/build/plain/efun/first_inventory#L32

*I'll reluctantly note that there are "harder" choices we could consider if we really want to have our cake and eat it, too. I could, for example, add more custom code so that we can include all of the admonitions in the flow where they're declared, and also collect them all and present a list near the end of the document (the HTML version could even link back to the original). With sufficient magic/fairy-dust the HTML version could present them in the flow with the list "minimized", while the plaintext version could just have footnote-esque references to the admonition list. I suspect this'll be a time-sink, so I'm only inclined to pursue it if we feel the "list" is essential for the plaintext docs.

[zesstra]

I would prefer approach 1) for the same reasons you already mentioned. However I can also live with 2). Argument against 1) is the not so nice plain text representation... Can we live with that?

[zesstra]

Ah, and I would defintely prefer to have as little custom code for sphinx/docutils as possible. ;-)

[abathur]

@zesstra I agree wrt to minimizing custom code, but if documentation consumers feel like following 1) makes the docs hard to use, that seems like a good justification for some.

I should also note that we can also just change how each individual admonition is translated for the plaintext. We could make them more visible without doing something more complex like presenting them two completely different ways. For example, we could take:

Warning: This could blow up the widgets

and make it:

<!> WARNING: This could blow up the widgets

[abathur]

I am going to go with 1 above, in addition to making the plaintext labels stand out a little bit better with some decoration as mentioned in my previous comment above.

[abathur]

Reopening until tags like this are implemented, but marking decided.

[abathur]

Ended up doing two things, though we may not really need both: the admonition title is prefixed with a <!> flag to draw attention, and the admonition title appears on its own line, with the body of the admonition indented on subsequent lines below it.

[zesstra]

Ok, sounds good. BTW: We may also ask people with vision impairment using screenreaders or braille devices for their opinion (giving them an example of future manpages). Just came to my mind. We have a few of them playing in Morgengrauen, we could ask them at a suitable time.

[abathur]

That would be a good process in general. We may also be able to generate (or make it possible to generate) a copy that works better with screen readers.