Do not inherit unnumbered property: help needed

Do not inherit unnumbered property: help needed

[Akater]

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

I have to deal with a document that has an unfortunate vague structure
which involves unnumbered headlines spanning a couple of numbered
ones. I'd like to convert the document into Org and thus effectively
need to implement a feature that would allow unnumbered property in Org
not to be inherited by children of unnumbered items in some cases.

Say, in the following toy example

#+BEGIN_SRC org
* section-one-title
blah
* the first two prime-numbered sections (duh)
:properties:
:ignore-this-outline-level: t
:unnumbered: t
:end:
** section-two-title
blah
** section-three-title
blah
* section-four-title
blah
#+END_SRC

section-three and section-four would be treated as being on the same
level as other section-x's, their children treated correspondingly.

For exporting needs, I chose to format the unnumbered headline the
same style as section-x's, only unnumbered, and have section-two and
section-three be numbered as if the unnumbered headline didn't
exist.

First,
I need to mark (?) parts of the parse tree that are children of
the unnumbered item, and are not explicitly marked unnumbered
themselves, as exportable when being passed to
org-export--collect-headline-numbering.

This is where I ask for help, as it's not clear to me how to do that.
My hypothesis so far was that org-export--prune-tree from ox.el filters
out unnumbered items but my attempts with debug-on-entry did not confirm
this. Could someone help?

Re: (?) maybe children are never marked as exportable in the first place
and the tree just does not get traversd too deep. Again, I don't yet see
which function is to be patched to let them through.

Second,
I will also need to redefine specialized functions like
org-html-section, turning
org-export-get-headline-number
into
org-export-get-deepest-numbered-parent-headline-number
and so on, but this doesn't seem to be difficult. However, if I'm
missing something and you think this could be a valuable feature, you
are welcome to share your thoughts. I'm not an experienced programmer
but hopefully I can implement this and contribute.
n(Will sign anything FSF if needed.)

I admit that the whole idea to add this to Org is questionable, and
documents structured like this better be restructured altogether. It is
likely that exported versions for some backends are not going to be
structured properly. (As far as I can see, Texinfo looks particularly
unpromising.)

Nevertheless, it is possible to at least make exported versions /look/
ok and describe possible backend-related caveats in the documentation.
I find it reasonable to keep org files structured properly, while
considering exported versions to be more of an eye candy. In my case,
the document in question is an archive entry which cannot be changed
retrospectively but me and my colleagues could still benefit from it
being tidily marked up.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 800 bytes --]

Re: Do not inherit unnumbered property: help needed

[Kaushal Modi]

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

On Fri, Nov 17, 2017, 7:00 AM Akater <nuclearspace@gmail.com> wrote:

> I have to deal with a document that has an unfortunate vague structure
> which involves unnumbered headlines spanning a couple of numbered
> ones. I'd like to convert the document into Org and thus effectively
> need to implement a feature that would allow unnumbered property in Org
> not to be inherited by children of unnumbered items in some cases.
>
> Say, in the following toy example
>
> #+BEGIN_SRC org
> * section-one-title
> blah
> * the first two prime-numbered sections (duh)
> :properties:
> :ignore-this-outline-level: t
> :unnumbered: t
> :end:
> ** section-two-title
> blah
> ** section-three-title
> blah
> * section-four-title
> blah
> #+END_SRC
>


Have you looked at org-use-property-inheritance variable
http://orgmode.org/manual/Property-inheritance.html -- You can set that to
a regexp that does not match UNNUMBERED.

section-three and section-four would be treated as being on the same
> level as other section-x's, their children treated correspondingly.
>

That won't be possible unless you define a custom exporter with it's custom
property that doctors the level interpreted from the leading stars.

For exporting needs, I chose to format the unnumbered headline the
> same style as section-x's, only unnumbered,


I don't see why that wouldn't be possible.

 and

have section-two and
> section-three be numbered as if the unnumbered headline didn't
> exist.
>

That's the default behavior too.

First,
> I need to mark (?) parts of the parse tree that are children of
> the unnumbered item, and are not explicitly marked unnumbered
> themselves, as exportable when being passed to
> org-export--collect-headline-numbering.
>

I don't think that is needed. The numbering of the headings after the
unnumbered headings stays the same whether or not you export the unnumbered
heading.

Second,
> I will also need to redefine specialized functions like
> org-html-section, turning
> org-export-get-headline-number
> into
> org-export-get-deepest-numbered-parent-headline-number
> and so on, but this doesn't seem to be difficult. However, if I'm
> missing something and you think this could be a valuable feature, you
> are welcome to share your thoughts.


Can you explain more on what features you propose for those functions so
that people can comment?

I'm not an experienced programmer
> but hopefully I can implement this and contribute.
> n(Will sign anything FSF if needed.)
>

Signing FSF as the first step is usually a good thing. So that with the
paperwork in place, you can contribute to Org/Emacs whenever you get a
chance in future.

I admit that the whole idea to add this to Org is questionable, and
> documents structured like this better be restructured altogether.


I didn't follow that.

It is
> likely that exported versions for some backends are not going to be
> structured properly. (As far as I can see, Texinfo looks particularly
> unpromising.)
>

?

>
Nevertheless, it is possible to at least make exported versions /look/
> ok and describe possible backend-related caveats in the documentation.
> I find it reasonable to keep org files structured properly, while
> considering exported versions to be more of an eye candy. In my case,
> the document in question is an archive entry which cannot be changed
> retrospectively but me and my colleagues could still benefit from it
> being tidily marked up.
>

I didn't follow all that you mentioned in the end. It's not clear what the
document restructuring was about after the initial problem statements.
Let's start with resolving the UNNUMBERED property non-inheritance.

> --

Kaushal Modi

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

Re: Do not inherit unnumbered property: help needed

[Akater]

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

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Have you looked at org-use-property-inheritance variable
> http://orgmode.org/manual/Property-inheritance.html -- You can set that to
> a regexp that does not match UNNUMBERED.

As this page mentions, default value is nil, which means nothing would be
inherited. UNNUMBERED does not follow this rule, even though it is not
mentioned as one “for which inheritance is hard-coded” in the manual ---
as was announced in org-news,
> *** Export unnumbered headlines

> Headlines, for which the property ~UNNUMBERED~ is non-nil, are now
> exported without section numbers irrespective of their levels.  The
> property is inherited by children.
http://orgmode.org/cgit.cgi/org-mode.git/plain/etc/ORG-NEWS

See also
Org Manual > Exporting > Export Settings
which also mentions
> Set `UNNUMBERED' property to non-`nil' to disable
>      numbering of heading and subheadings entirely.
Not a single word in the manual, or in worg, on disabling this
particular kind of inheritance.

After evaluating
(setq org-use-property-inheritance "[^\\(UNNUMBERED\\)]")
children are still exported numbered. org-reload has no additional
effect. I use Org 9.1.3 (20171116 from melpa) and Emacs 25.3.1.

In case UNNUMBERED's inheritance could be turned off by a standard
procedure, my other points are meaningless. So let's first figure out if
it could.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 800 bytes --]

Re: Do not inherit unnumbered property: help needed

[Nicolas Goaziou]

Hello,

Akater <nuclearspace@gmail.com> writes:

> In case UNNUMBERED's inheritance could be turned off by a standard
> procedure, my other points are meaningless. So let's first figure out if
> it could.

It cannot. That's a feature intended to preserve sanity.

As suggested, you could write an export back-end that ignore UNNUMBERED
inheritance.

OOC, what is the output you expect from your initial example?

Regards,

-- 
Nicolas Goaziou

Re: Do not inherit unnumbered property: help needed

[Akater]

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

On November 17, 2017 10:09:55 PM GMT+00:00, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
>OOC, what is the output you expect from your initial example?
>

in LaTeX:

* section-one
blah
* unnumbered-header
:PROPERTIES:
:UNNUMBERED:
:SKIP-OUTLINE-LEVEL:
:END:
** section-two
blah
** section-three
blah
* section-four
blah

should export as

\section{section-one}
blah
\section*{unnumbered-header}
\section{section-two}
blah
\section{section-three}
blah
\section{section-four}
blah

I agree, this is structurally incorrect but will look ok, or can be made look ok.
This is the first time I post to mailing list from K9-mail, hopefully it goes to proper thread, sorry if doesn't.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 845 bytes --]

Re: Do not inherit unnumbered property: help needed

[Nicolas Goaziou]

Hello,

Akater <nuclearspace@gmail.com> writes:

> On November 17, 2017 10:09:55 PM GMT+00:00, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>>
>>OOC, what is the output you expect from your initial example?
>>
>
> in LaTeX:
>
> * section-one
> blah
> * unnumbered-header
> :PROPERTIES:
> :UNNUMBERED:
> :SKIP-OUTLINE-LEVEL:
> :END:
> ** section-two
> blah
> ** section-three
> blah
> * section-four
> blah
>
> should export as
>
> \section{section-one}
> blah
> \section*{unnumbered-header}
> \section{section-two}
> blah
> \section{section-three}
> blah
> \section{section-four}
> blah
>
> I agree, this is structurally incorrect but will look ok, or can be
> made look ok.

I see. I don't think UNNUMBERED should be able to modify the structure
of the document. I suggest to write a parse tree filter that does that
change to the tree.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: Do not inherit unnumbered property: help needed

[Akater]

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

On November 18, 2017 5:18:10 PM GMT+00:00, Nicolas Goaziou 
>I see. I don't think UNNUMBERED should be able to modify the structure
>of the document. I suggest to write a parse tree filter that does that
>change to the tree.
>
>Regards,

Please note: it is not UNNUMBERED that modifies the structure in my suggestion but rather SKIP-OUTLINE-LEVEL.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 845 bytes --]

Re: Do not inherit unnumbered property: help needed

[Akater]

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

On November 18, 2017 5:18:10 PM GMT+00:00, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> I suggest to write a parse tree filter that does that
>change to the tree.
>
I got an impression that UNNUMBERED's children get cut off prior to what user can do, hence writing a simple backend won't help, and I'll have to patch org (ox) source. Do you know for sure I'm wrong? That's what I asked for originally---which function is responsible for excluding unnumbered's children from exported entries.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 845 bytes --]

Re: Do not inherit unnumbered property: help needed

[Nicolas Goaziou]

Hello,

Akater <nuclearspace@gmail.com> writes:

> I got an impression that UNNUMBERED's children get cut off prior to
> what user can do,

UNNUMBERED headings are not cut off, at least not by "ox.el".

> hence writing a simple backend won't help, and I'll have to patch org
> (ox) source. Do you know for sure I'm wrong?

I'm quite certain you're wrong.

> That's what I asked for
> originally---which function is responsible for excluding unnumbered's
> children from exported entries.

Three functions actually check UNNUMBERED properties:

- org-export-numbered-headline-p
- org-export-collect-headlines
- org-export-excluded-from-toc-p

You can ignore the last two because it's a special case (when value is
"notoc").

So, if you want to control UNNUMBERED property, just don't trust
`org-export-numbered-headline-p', or any function calling it.

Regards,

-- 
Nicolas Goaziou

Re: Do not inherit unnumbered property: help needed

[Nicolas Goaziou]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:


> Akater <nuclearspace@gmail.com> writes:
>
>> I got an impression that UNNUMBERED's children get cut off prior to
>> what user can do,
>
> UNNUMBERED headings are not cut off, at least not by "ox.el".
>
>> hence writing a simple backend won't help, and I'll have to patch org
>> (ox) source. Do you know for sure I'm wrong?
>
> I'm quite certain you're wrong.
>
>> That's what I asked for
>> originally---which function is responsible for excluding unnumbered's
>> children from exported entries.
>
> Three functions actually check UNNUMBERED properties:
>
> - org-export-numbered-headline-p
> - org-export-collect-headlines
> - org-export-excluded-from-toc-p
>
> You can ignore the last two because it's a special case (when value is
> "notoc").
>
> So, if you want to control UNNUMBERED property, just don't trust
> `org-export-numbered-headline-p', or any function calling it.

On second thought, we might as well give more flexibility to the users,
that is, as long as one doesn't expect to get something meaningful from
every UNNUMBERED combination.

It is now possible to change UNNUMBERED status mid-tree, like any other
inherited property.

Regards,