Christian Moe <[email protected]> writes:
I'm thinking about standardization mostly in case the ob-doc-*
documentation is added to the Org manual, but a uniform look
and feel
on Worg would be nice, too. A solution that looks good on Worg
and
ports easily to the Org manual would be best.
Right, that's a point in favor of standardization that I didn't
consider. What's the thinking on how Babel language docs should
look in
the manual? Should images be used at all? Can/should live src
blocks be
used in org-manual.org? I see the current Babel examples in
org-manual.org wrap src blocks and results in #+begin_example
with Org
keywords comma-escaped.
I don't know what the thinking is on how the Babel language docs
should look. We're still pretty far away from finishing the
documentation on Worg, which means the move to the manual isn't
imminent.
Years ago, I thought live source docs on Worg would be cool for
users who clone the repo, but I've come to the conclusion that the
costs outweigh potential benefits. I'd like to make all the
ob-doc-*.org files static, if possible, with a consistent use of
#+begin_example/#+end_example.
ATM, I'm copy editing for markup conventions, following this
guide:
- When to use = ... = or ~ ... ~ markup:
+ files or extensions use = ... =,
+ anything that is meant to be written in the Org buffer uses =
... =,
+ any meaningful token in a programming language uses ~ ... ~.
All the best,
Tom
--
Thomas S. Dye
https://tsdye.online/tsdye
