Re: [RFC] Moving "manual.org" into core

[Kaushal Modi <kaushal.modi@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1634 bytes --]

On Mon, Jan 22, 2018 at 11:02 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> "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.

[1]:
https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org


-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2777 bytes --]