Hello again :),
Let me provide examples -- using footnotes.
All footnote references and definitions would be inside
$[...]. (As mentioned in my previous post.)
There was a concern about keeping code executable. You can
use a parameter to specify whether you want the footnote to:
- disappear in the code (thus keeping the code executable
without having to use comments, so that the reference is
at the correct position in the line, yet keeping the
link pointing to the correct position)
- or show up as a numbered or labeled reference
The reference can look like:
(defun my-example-defun $[fn "defun name" :invisible t] ()
(interactive "P") ;$[fn "interactive"]
...
The second reference is visible, but the first is not. Note
that this allows references with spaces (or anything else).
No need to worry about syntax conflicts within org.
There was also a concern about conflicting with code syntax.
Your decision as a user is whether you want $[...] to be
interpreted as code or footnote. You could want either one.
To make it be interpreted as code, you simply prefix the $
with a \. That takes away org's special handling of the
syntax. org's footnote code merely checks for a \ in front
of the $ and then it knows not to do anything except remove
the \.
In fact, the footnote code doesn't even have to do that.
The org extensible syntax code (the code for $[...]) is what
does it. The footnote code simply calls the extensible
syntax code.
To make it be a footnote, you don't do anything.
This will work for all code examples you can dream up.
There is no need to worry about which languages have $[...]
in them.
The advantage is that for future features, the same
solutions will work. And since the syntax is extensible, it
will work for completely new features.
Finally, the escaping scheme should be familiar to users, as
it is a common method in programming languages.
Is this idea possibly of interest?