"manual.org" is not meant to be exported to HTML through "ox-html", but
using Texinfo itself. AFAIK, Texinfo does not highlight specially Org
syntax, so using "begin_src org" is not very important for export.
I am hoping that using "begin_src org" preserves the meta data that a code block is an Org snippet when the Org manual HTML pages are published on
orgmode.org.
Moreover, the advantage of using "begin_example" instead is:
1. we can use fixed-width for one-liners,
I personally don't see that as a big advantage. Whether the snippet is a single line or more, one can just select those and use the Org structural template insertion to wrap that with "#+begin_src org" .. "#+end_src".
2. Org fontification for source blocks can be sometimes misleading,
as you sometimes cannot what is an example and what is not.
I didn't understand that limitation. I use Org src blocks quite liberally in this Org document[1], some even with nested non-Org src blocks.
#+BEGIN_SRC org :noweb-ref src-block-n-default-continue
,#+BEGIN_SRC emacs-lisp +n
;; This will be listed as line 22
(message "This is line 23")
,#+END_SRC
#+END_SRC
I haven't found any issue.
While pasting that example, I realized, that you don't even need to specially made an Org snippet an src block just because you want to use it as a noweb ref in the manual. Making Org snippets, src blocks, always, just feels like the right thing.