Configurable prefixes for heading-tree numbering in HTML export? ($)

Configurable prefixes for heading-tree numbering in HTML export? ($)

[D. C. Toedt]

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

So far as I can tell, org-mode currently allows heading numbering in only
one style (1, 1.1, 1.1.1, etc.).  For HTML export, I'm interested in having
the heading numbering be configurable on a per-subtree basis, along
something like the following lines for a hypothetical consulting-agreement
contract  (indentation is for convenient reading only).  This is for my Common
Draft <http://www.CommonDraft.org> contract terms and conditions project
--- I'd like to be able to arrange the trees in an arbitrary order and have
the top-level headings start with prefixes and heading numbers instead of
heading numbers alone.

This can be done in a very kludgy fashion with CSS (see below), but doing
it in org-mode would be far preferable for several reasons.

I'd be happy to pay an honorarium, or make a donation, of USD$100-$200 for
the appropriate elisp code that I could include in the relevant file(s).
I'd want the elisp code to be open-sourced, and at least minimal
documentation, so that it could be made a candidate for possible inclusion
in a future org-mode release.

Here's an example of the desired org-mode code:


===BEGIN===


* Services

  :PROPERTIES:

  :CUSTOM_ID: SVC

  :CUSTOM_PREFIX: t

  :END:
# ======== NOTE THE :CUSTOM_PREFIX: property above =========== #


** Statements of Work

[properties and text omitted]


*** Written Statements of Work Required

[properties and text omitted]
# =========== AN ARBITRARY NUMBER OF SUBHEADING LEVELS BENEATH THE TOP
LEVEL ============= #


*** Changes Must Be in Writing
[properties and text omitted]



** Billing Rates

[properties and text omitted]


** IP Ownership

[properties and text omitted]


* General Provisions

  :PROPERTIES:

  :CUSTOM_ID: GP
  :CUSTOM_PREFIX: t

  :END:


** Amendments

[properties and text omitted]


** Notices

[properties and text omitted]

===END===


I'd like for the resulting HTML export to be something like the following:

SVC Services

# ======== NOTE THAT THERE'S NO HEADING /NUMBER/ FOR THE TOP-LEVEL HEADING,
JUST THE PREFIX ========== #


SVC-1 Statements of Work

[properties and text omitted]

# ======== PREFERABLY THE SEPARATOR IN "SVC-1" COULD BE CONFIGURED AS A
HYPHEN, A PERIOD, A COLON, A FORWARD SLASH, ETC. ============= #


SVC-1.1  Written Statements of Work Required

[properties and text omitted]

SVC-1.2  Changes Must Be in Writing

[properties and text omitted]


SVC-2 Billing Rates

[properties and text omitted]


SVC-3 IP Ownership

[properties and text omitted]


GP General Provisions


GP-1 Amendments

[properties and text omitted]


GP-2 Notices

[properties and text omitted]



I've played with doing this in CSS --- a suboptimal solution would be to:

   1. set the :UNNUMBERED: property to non-nil
   2. define separate CSS div classes for each top-level heading (e.g., SVC
   and GP in the examples above)
   3. for each top-level heading in question:
      1. use the :HTML_CONTAINER_CLASS: property to specify the div class
      for that top-level heading
      2. for each subheading level in that div class, use the
      psuedo-element ":before" to add the appropriate prefix and counter

Apart from being kludgy, doing it this way (in CSS) would eliminate
org-mode's ability to produce automatic cross-referencing during export.
Also, the heading numbers wouldn't transfer over when copying and pasting
from HTML to a Word document, which is an important user feature.

In case it matters, I run the 2016-07-25 release of org-mode on Emacs
25.1.50 (9.0) with the most recent update of Mac OS X El Capitan.  I know a
little about elisp and have cobbled together a few simple functions for my
own use, but I'm far from being even minimally competent at it.

Any ideas for an org-mode elisp solution?

​Thanks in advance,

--D. C.

D. C. Toedt III
*(My last name is pronounced "Tate")*
Attorney & arbitrator -- tech contracts & IP
O: +1 (713) 364-6545   C: +1 (713) 516-8968
​​

dc@toedt.com    @dctoedt <https://twitter.com/DCToedt>
​
Skype: dctoedt
​

www.OnContracts.com/About <http://www.oncontracts.com/About>
​​


Unless expressly stated otherwise,
this message is not intended to serve
as assent to an agreement or other document,
even if attached to this message.

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

Re: Configurable prefixes for heading-tree numbering in HTML export? ($)

[Nicolas Goaziou]

Hello,

"D. C. Toedt" <dc@toedt.com> writes:

> So far as I can tell, org-mode currently allows heading numbering in only
> one style (1, 1.1, 1.1.1, etc.).  For HTML export, I'm interested in having
> the heading numbering be configurable on a per-subtree basis, along
> something like the following lines for a hypothetical consulting-agreement
> contract  (indentation is for convenient reading only).  This is for my Common
> Draft <http://www.CommonDraft.org> contract terms and conditions project
> --- I'd like to be able to arrange the trees in an arbitrary order and have
> the top-level headings start with prefixes and heading numbers instead of
> heading numbers alone.
>
> This can be done in a very kludgy fashion with CSS (see below), but doing
> it in org-mode would be far preferable for several reasons.
>
> I'd be happy to pay an honorarium, or make a donation, of USD$100-$200 for
> the appropriate elisp code that I could include in the relevant file(s).
> I'd want the elisp code to be open-sourced, and at least minimal
> documentation, so that it could be made a candidate for possible inclusion
> in a future org-mode release.
>
> Here's an example of the desired org-mode code:
>
>
> ===BEGIN===
>
>
> * Services
>
>   :PROPERTIES:
>
>   :CUSTOM_ID: SVC
>
>   :CUSTOM_PREFIX: t
>
>   :END:
> # ======== NOTE THE :CUSTOM_PREFIX: property above =========== #
>
>
> ** Statements of Work
>
> [properties and text omitted]
>
>
> *** Written Statements of Work Required
>
> [properties and text omitted]
> # =========== AN ARBITRARY NUMBER OF SUBHEADING LEVELS BENEATH THE TOP
> LEVEL ============= #
>
>
> *** Changes Must Be in Writing
> [properties and text omitted]
>
>
>
> ** Billing Rates
>
> [properties and text omitted]
>
>
> ** IP Ownership
>
> [properties and text omitted]
>
>
> * General Provisions
>
>   :PROPERTIES:
>
>   :CUSTOM_ID: GP
>   :CUSTOM_PREFIX: t
>
>   :END:
>
>
> ** Amendments
>
> [properties and text omitted]
>
>
> ** Notices
>
> [properties and text omitted]
>
> ===END===
>
>
> I'd like for the resulting HTML export to be something like the following:
>
> SVC Services
>
> # ======== NOTE THAT THERE'S NO HEADING /NUMBER/ FOR THE TOP-LEVEL HEADING,
> JUST THE PREFIX ========== #
>
>
> SVC-1 Statements of Work
>
> [properties and text omitted]
>
> # ======== PREFERABLY THE SEPARATOR IN "SVC-1" COULD BE CONFIGURED AS A
> HYPHEN, A PERIOD, A COLON, A FORWARD SLASH, ETC. ============= #
>
>
> SVC-1.1  Written Statements of Work Required
>
> [properties and text omitted]
>
> SVC-1.2  Changes Must Be in Writing
>
> [properties and text omitted]
>
>
> SVC-2 Billing Rates
>
> [properties and text omitted]
>
>
> SVC-3 IP Ownership
>
> [properties and text omitted]
>
>
> GP General Provisions
>
>
> GP-1 Amendments
>
> [properties and text omitted]
>
>
> GP-2 Notices
>
> [properties and text omitted]
>

Possibly not what you're asking but, you can ignore CUSTOM_PREFIX
property altogether and use a headline filter to do what you want.

  (defun my-heading-prefix-filter (heading backend info)
    "Prefix every heading and sub-heading with custom ID.
  Skip one level of numbering."
    (when (org-export-derived-backend-p backend 'html)
      (let ((internal-ref
             (and (string-match "\\`.*id=\"outline-container-\\(.+?\\)\"" heading)
                  (match-string 1 heading)))
            (id (and (string-match "\\`.*\n<h[0-9]+ id=\"\\(.*?\\)\">" heading)
                     (match-string 1 heading))))
        ;; When there is no custom ID, id attribute contains the
        ;; internal reference.  So we check if there is a custom ID which
        ;; is going to become the prefix of all headings.
        (unless (equal internal-ref id)   ;No custom ID
          (let ((s 0))
            (while (string-match
                    "\\(<h.+?>\\)\\(?:.*?<span class=\"section-number-[0-9]+\">\\(.+?\\)</span>\\)?"
                    heading s)
              (setq s (+ (match-end 0) (length id) 1))
              (setq heading
                    (cond
                     ;; Unnumbered heading.
                     ((not (match-end 2))
                      (replace-match (concat "\\1" id " ") nil nil heading 1))
                     ;; Top level heading.  Ignore numbering.
                     ((string-match-p "\\`[0-9]+\\'" (match-string 2 heading))
                      (replace-match id nil nil heading 2))
                     ;; Sub-headings.  Skip first number.
                     (t
                      (let ((numbers
                             (save-match-data
                               (split-string (match-string 2 heading) "\\."))))
                        (replace-match
                         (concat id "-" (mapconcat #'identity (cdr numbers) "."))
                         nil nil heading 2))))))
            heading)))))

  (add-to-list 'org-export-filter-headline-functions
               'my-heading-prefix-filter)

custom ID is used to prefix every heading with its value.  Of course, it
means that every heading with a custom ID is expected to follow this
pattern, so you cannot toggle the feature subtree wise. Anyway that's
a starting point.

Regards,

-- 
Nicolas Goaziou

Re: Configurable prefixes for heading-tree numbering in HTML export? ($)

[D. C. Toedt]

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

Many thanks, Nick -- an interesting approach, but it's not a good fit for
what I need.

Another approach would be possible if org-mode had a way of including
arbitrary attribute text in HTML exports of headings.  This would enable
use of the CSS attr()
<https://developer.mozilla.org/en-US/docs/Web/CSS/attr>functionality,
combined with the ::before pseudo-element and counters.   I've tested out
the following in HTML; it seems to work for what I need:

==BEGIN HTML SNIPPET==

<style>
body   { counter-reset: section-counter; }
h2      { counter-reset: sub-section-counter; }
h3  { counter-reset: sub-sub-section-counter; }

h2::before {
    counter-increment: section-counter;
    content: attr(CDArticlePrefix) "-" counter(section-counter) " ";
}

h3:before {
    counter-increment: sub-section-counter;
    content: attr(CDArticlePrefix) "-" counter(section-counter) "."
counter(sub-section-counter) " ";
}

h4:before {
    counter-increment: sub-sub-section-counter;
    content: attr(CDArticlePrefix) "-" counter(section-counter) "."
counter(sub-section-counter) "." counter(sub-sub-section-counter) " ";
}

</style>

<h2 CDArticlePrefix="DEFN">Definitions</h2> <!-- NOTE THE "CDArticlePrefix"
ATTRIBUTE -->

<h2 CDArticlePrefix="SERV">Consulting Services</h2>

<h2 CDArticlePrefix="PMT">Payment Terms</h2>

<h2 CDArticlePrefix="GPR">General Provisions</h2>

==END HTML SNIPPET==

Unfortunately, org-mode does not seem to be able to include the
CDArticlePrefix="DEFN" attribute text in headings, as opposed to in divs.

I appreciate the response.

Regards,

D. C.





D. C. Toedt III
*(My last name is pronounced "Tate")*
Attorney & arbitrator -- tech contracts & IP
O: +1 (713) 364-6545   C: +1 (713) 516-8968
​​

dc@toedt.com    @dctoedt <https://twitter.com/DCToedt>
​
Skype: dctoedt
​

www.OnContracts.com/About <http://www.oncontracts.com/About>
​​


Unless expressly stated otherwise,
this message is not intended to serve
as assent to an agreement or other document,
even if attached to this message.



On Sat, Jul 30, 2016 at 5:06 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> "D. C. Toedt" <dc@toedt.com> writes:
>
> > So far as I can tell, org-mode currently allows heading numbering in only
> > one style (1, 1.1, 1.1.1, etc.).  For HTML export, I'm interested in
> having
> > the heading numbering be configurable on a per-subtree basis, along
> > something like the following lines for a hypothetical
> consulting-agreement
> > contract  (indentation is for convenient reading only).  This is for my
> Common
> > Draft <http://www.CommonDraft.org> contract terms and conditions project
> > --- I'd like to be able to arrange the trees in an arbitrary order and
> have
> > the top-level headings start with prefixes and heading numbers instead of
> > heading numbers alone.
> >
> > This can be done in a very kludgy fashion with CSS (see below), but doing
> > it in org-mode would be far preferable for several reasons.
> >
> > I'd be happy to pay an honorarium, or make a donation, of USD$100-$200
> for
> > the appropriate elisp code that I could include in the relevant file(s).
> > I'd want the elisp code to be open-sourced, and at least minimal
> > documentation, so that it could be made a candidate for possible
> inclusion
> > in a future org-mode release.
> >
> > Here's an example of the desired org-mode code:
> >
> >
> > ===BEGIN===
> >
> >
> > * Services
> >
> >   :PROPERTIES:
> >
> >   :CUSTOM_ID: SVC
> >
> >   :CUSTOM_PREFIX: t
> >
> >   :END:
> > # ======== NOTE THE :CUSTOM_PREFIX: property above =========== #
> >
> >
> > ** Statements of Work
> >
> > [properties and text omitted]
> >
> >
> > *** Written Statements of Work Required
> >
> > [properties and text omitted]
> > # =========== AN ARBITRARY NUMBER OF SUBHEADING LEVELS BENEATH THE TOP
> > LEVEL ============= #
> >
> >
> > *** Changes Must Be in Writing
> > [properties and text omitted]
> >
> >
> >
> > ** Billing Rates
> >
> > [properties and text omitted]
> >
> >
> > ** IP Ownership
> >
> > [properties and text omitted]
> >
> >
> > * General Provisions
> >
> >   :PROPERTIES:
> >
> >   :CUSTOM_ID: GP
> >   :CUSTOM_PREFIX: t
> >
> >   :END:
> >
> >
> > ** Amendments
> >
> > [properties and text omitted]
> >
> >
> > ** Notices
> >
> > [properties and text omitted]
> >
> > ===END===
> >
> >
> > I'd like for the resulting HTML export to be something like the
> following:
> >
> > SVC Services
> >
> > # ======== NOTE THAT THERE'S NO HEADING /NUMBER/ FOR THE TOP-LEVEL
> HEADING,
> > JUST THE PREFIX ========== #
> >
> >
> > SVC-1 Statements of Work
> >
> > [properties and text omitted]
> >
> > # ======== PREFERABLY THE SEPARATOR IN "SVC-1" COULD BE CONFIGURED AS A
> > HYPHEN, A PERIOD, A COLON, A FORWARD SLASH, ETC. ============= #
> >
> >
> > SVC-1.1  Written Statements of Work Required
> >
> > [properties and text omitted]
> >
> > SVC-1.2  Changes Must Be in Writing
> >
> > [properties and text omitted]
> >
> >
> > SVC-2 Billing Rates
> >
> > [properties and text omitted]
> >
> >
> > SVC-3 IP Ownership
> >
> > [properties and text omitted]
> >
> >
> > GP General Provisions
> >
> >
> > GP-1 Amendments
> >
> > [properties and text omitted]
> >
> >
> > GP-2 Notices
> >
> > [properties and text omitted]
> >
>
> Possibly not what you're asking but, you can ignore CUSTOM_PREFIX
> property altogether and use a headline filter to do what you want.
>
>   (defun my-heading-prefix-filter (heading backend info)
>     "Prefix every heading and sub-heading with custom ID.
>   Skip one level of numbering."
>     (when (org-export-derived-backend-p backend 'html)
>       (let ((internal-ref
>              (and (string-match "\\`.*id=\"outline-container-\\(.+?\\)\""
> heading)
>                   (match-string 1 heading)))
>             (id (and (string-match "\\`.*\n<h[0-9]+ id=\"\\(.*?\\)\">"
> heading)
>                      (match-string 1 heading))))
>         ;; When there is no custom ID, id attribute contains the
>         ;; internal reference.  So we check if there is a custom ID which
>         ;; is going to become the prefix of all headings.
>         (unless (equal internal-ref id)   ;No custom ID
>           (let ((s 0))
>             (while (string-match
>                     "\\(<h.+?>\\)\\(?:.*?<span
> class=\"section-number-[0-9]+\">\\(.+?\\)</span>\\)?"
>                     heading s)
>               (setq s (+ (match-end 0) (length id) 1))
>               (setq heading
>                     (cond
>                      ;; Unnumbered heading.
>                      ((not (match-end 2))
>                       (replace-match (concat "\\1" id " ") nil nil heading
> 1))
>                      ;; Top level heading.  Ignore numbering.
>                      ((string-match-p "\\`[0-9]+\\'" (match-string 2
> heading))
>                       (replace-match id nil nil heading 2))
>                      ;; Sub-headings.  Skip first number.
>                      (t
>                       (let ((numbers
>                              (save-match-data
>                                (split-string (match-string 2 heading)
> "\\."))))
>                         (replace-match
>                          (concat id "-" (mapconcat #'identity (cdr
> numbers) "."))
>                          nil nil heading 2))))))
>             heading)))))
>
>   (add-to-list 'org-export-filter-headline-functions
>                'my-heading-prefix-filter)
>
> custom ID is used to prefix every heading with its value.  Of course, it
> means that every heading with a custom ID is expected to follow this
> pattern, so you cannot toggle the feature subtree wise. Anyway that's
> a starting point.
>
> Regards,
>
> --
> Nicolas Goaziou
>

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