* Org mode "style sheet" for software documentation
@ 2022-09-08 16:20 Perry Smith
2022-09-08 20:38 ` Perry Smith
2022-09-09 15:00 ` Max Nikulin
0 siblings, 2 replies; 6+ messages in thread
From: Perry Smith @ 2022-09-08 16:20 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 1794 bytes --]
I don’t understand this page: https://orgmode.org/worg/dev/org-syntax.html#Emphasis_Markers <https://orgmode.org/worg/dev/org-syntax.html#Emphasis_Markers>
In particular, the BORDER BODY BORDER part. Note that this is the CONTENT which is already between MARKERS.
What I *think* I want is the ability to effectively create what I’ll call “macros”. I’d like to be able to separate out things like file paths, code samples (both in line and block), keywords, environment variables, code variables, etc. So, as I write, I would do (as a total pretend example) [var]foo_dog[var] to denote foo_dog as a code variable. I’m wondering if that isn’t what the “BORDER” character is. From the way the section is written, I would assume the leading border character must be the same as the trailing border character so I could do ~vfoo_docv~ where the “v” would be the border character?
OR… perhaps what this is trying to tell me is the first character after the leading marker and the last character before the trailing marker must not be whitespace characters since that is how it appears from all of the examples.
My logic is if I take the time to separate out all of the elements as I write the document, then I can later decide to format, for example, code snippets the same as variables. It would also help me to be more consistent while I write because I’m (currently) having to remember “Ok… how did I format variables? Was that ‘code' or ‘italics'? … Hmm…”
If I’ve misunderstood this page, then perhaps to save a follow up email, can someone tell me if I can create “macros” within Org mode to do what I mentioned OR tell me that I really don’t want to go down that path for some reason.
Thank you for your help,
Perry
[-- Attachment #1.2: Type: text/html, Size: 2429 bytes --]
[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Org mode "style sheet" for software documentation
2022-09-08 16:20 Org mode "style sheet" for software documentation Perry Smith
@ 2022-09-08 20:38 ` Perry Smith
2022-09-09 5:09 ` Ihor Radchenko
2022-09-09 15:00 ` Max Nikulin
1 sibling, 1 reply; 6+ messages in thread
From: Perry Smith @ 2022-09-08 20:38 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 2607 bytes --]
> On Sep 8, 2022, at 11:20, Perry Smith <pedz@easesoftware.com> wrote:
>
> I don’t understand this page: https://orgmode.org/worg/dev/org-syntax.html#Emphasis_Markers <https://orgmode.org/worg/dev/org-syntax.html#Emphasis_Markers>
>
> In particular, the BORDER BODY BORDER part. Note that this is the CONTENT which is already between MARKERS.
>
> What I *think* I want is the ability to effectively create what I’ll call “macros”. I’d like to be able to separate out things like file paths, code samples (both in line and block), keywords, environment variables, code variables, etc. So, as I write, I would do (as a total pretend example) [var]foo_dog[var] to denote foo_dog as a code variable. I’m wondering if that isn’t what the “BORDER” character is. From the way the section is written, I would assume the leading border character must be the same as the trailing border character so I could do ~vfoo_docv~ where the “v” would be the border character?
>
> OR… perhaps what this is trying to tell me is the first character after the leading marker and the last character before the trailing marker must not be whitespace characters since that is how it appears from all of the examples.
>
> My logic is if I take the time to separate out all of the elements as I write the document, then I can later decide to format, for example, code snippets the same as variables. It would also help me to be more consistent while I write because I’m (currently) having to remember “Ok… how did I format variables? Was that ‘code' or ‘italics'? … Hmm…”
>
> If I’ve misunderstood this page, then perhaps to save a follow up email, can someone tell me if I can create “macros” within Org mode to do what I mentioned OR tell me that I really don’t want to go down that path for some reason.
From the code:
Terminology: In an emphasis string
like " *strong word* ", we call the initial space PREMATCH, the final
space POSTMATCH, the stars MARKERS, "s" and "d" are BORDER characters
and "trong wor" is the body.
The code has clearer documentation than the documentation :-)
So… it seems I didn’t the two BORDER characters do not need to match. So I’m off trying to figure out a way to create more emphasis MARKERS. In the old days, we had only about 43 non-alphanumeric characters to play with but now with Emacs being 8 bit clean for countless years we have another 128 characters and with UTF-8 we have bazillians more!
So I’m gently poking around in the code to see how hard it would be to define more.
pedz
[-- Attachment #1.2: Type: text/html, Size: 3999 bytes --]
[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Org mode "style sheet" for software documentation
2022-09-08 20:38 ` Perry Smith
@ 2022-09-09 5:09 ` Ihor Radchenko
2022-09-09 12:42 ` Perry Smith
0 siblings, 1 reply; 6+ messages in thread
From: Ihor Radchenko @ 2022-09-09 5:09 UTC (permalink / raw)
To: Perry Smith; +Cc: emacs-orgmode
Perry Smith <pedz@easesoftware.com> writes:
> So… it seems I didn’t the two BORDER characters do not need to match. So I’m off trying to figure out a way to create more emphasis MARKERS. In the old days, we had only about 43 non-alphanumeric characters to play with but now with Emacs being 8 bit clean for countless years we have another 128 characters and with UTF-8 we have bazillians more!
>
> So I’m gently poking around in the code to see how hard it would be to define more.
We currently do not support extensions to emphasis, though we may do it
in future. See https://orgmode.org/list/87letvrege.fsf@localhost
Implementing new emphasis markers will require introducing a new syntax
object into org-element.el. Such object will unlikely be using a
single-char markers - single-char markers are problematic in numerous
edge cases; we should better introduce something closer to inline src
block syntax to allow arbitrary emphasis extensions.
--
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Org mode "style sheet" for software documentation
2022-09-09 5:09 ` Ihor Radchenko
@ 2022-09-09 12:42 ` Perry Smith
2022-09-10 4:44 ` Ihor Radchenko
0 siblings, 1 reply; 6+ messages in thread
From: Perry Smith @ 2022-09-09 12:42 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1295 bytes --]
> On Sep 9, 2022, at 00:09, Ihor Radchenko <yantar92@gmail.com> wrote:
>
> Perry Smith <pedz@easesoftware.com> writes:
>
>> So… it seems I didn’t the two BORDER characters do not need to match. So I’m off trying to figure out a way to create more emphasis MARKERS. In the old days, we had only about 43 non-alphanumeric characters to play with but now with Emacs being 8 bit clean for countless years we have another 128 characters and with UTF-8 we have bazillians more!
>>
>> So I’m gently poking around in the code to see how hard it would be to define more.
>
> We currently do not support extensions to emphasis, though we may do it
> in future. See https://orgmode.org/list/87letvrege.fsf@localhost
>
> Implementing new emphasis markers will require introducing a new syntax
> object into org-element.el. Such object will unlikely be using a
> single-char markers - single-char markers are problematic in numerous
> edge cases; we should better introduce something closer to inline src
> block syntax to allow arbitrary emphasis extensions.
I’m now retired with time on my hands so ping me if I can help somehow if / when the time
comes. I sometimes turn off receiving from the list so drop me an email directly to
make sure I see it.
Perry
[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Org mode "style sheet" for software documentation
2022-09-08 16:20 Org mode "style sheet" for software documentation Perry Smith
2022-09-08 20:38 ` Perry Smith
@ 2022-09-09 15:00 ` Max Nikulin
1 sibling, 0 replies; 6+ messages in thread
From: Max Nikulin @ 2022-09-09 15:00 UTC (permalink / raw)
To: Perry Smith, emacs-orgmode
On 08/09/2022 23:20, Perry Smith wrote:
> I’d like to be able to separate out things like file
> paths, code samples (both in line and block), keywords, environment
> variables, code variables, etc.
...
> It would also help me to be more
> consistent while I write because I’m (currently) having to remember “Ok…
> how did I format variables? Was that ‘code' or ‘italics'? … Hmm…”
Depending on export backend and desired output quality you may use
info "(org) Macro Replacement"
https://orgmode.org/manual/Macro-Replacement.html or you may define
custom link type with :export property and type e.g.
[[style:file-path][/dev/null]]. The latter is a kind of hack, but it
might be more convenient in some cases.
E.g. macros are used in the doc/org-manual.org file
{{{kbd(M-x list-packages)}}}
see doc/doc-setup.org for its definition.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Org mode "style sheet" for software documentation
2022-09-09 12:42 ` Perry Smith
@ 2022-09-10 4:44 ` Ihor Radchenko
0 siblings, 0 replies; 6+ messages in thread
From: Ihor Radchenko @ 2022-09-10 4:44 UTC (permalink / raw)
To: Perry Smith; +Cc: emacs-orgmode
Perry Smith <pedz@easesoftware.com> writes:
>> We currently do not support extensions to emphasis, though we may do it
>> in future. See https://orgmode.org/list/87letvrege.fsf@localhost
>>
>> Implementing new emphasis markers will require introducing a new syntax
>> object into org-element.el. Such object will unlikely be using a
>> single-char markers - single-char markers are problematic in numerous
>> edge cases; we should better introduce something closer to inline src
>> block syntax to allow arbitrary emphasis extensions.
>
> I’m now retired with time on my hands so ping me if I can help somehow if / when the time
> comes. I sometimes turn off receiving from the list so drop me an email directly to
> make sure I see it.
If you are interested in an involved contribution, it is the most
welcome.
We currently have plans to implement fully custom elements and objects
in Org. The idea is to allow the
:export/:activate-func/:face/:keymap/:export functionality like in Org
links, but for special blocks and inline objects. I can provide more
details if you are interested.
--
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-09-10 4:44 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-09-08 16:20 Org mode "style sheet" for software documentation Perry Smith
2022-09-08 20:38 ` Perry Smith
2022-09-09 5:09 ` Ihor Radchenko
2022-09-09 12:42 ` Perry Smith
2022-09-10 4:44 ` Ihor Radchenko
2022-09-09 15:00 ` Max Nikulin
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).