How to do proper folding and semantic markup

How to do proper folding and semantic markup

[Eduardo Mercovich]

Dear all.

I'm using org-mode as a writer and it is simply fantastic. One of the
things I enjoy more is the folding. A huge report like the one I'm
working on seems sooo easy... ;)

However, I don't know how to integrate that with some semantic markup
and the latex exporter at the same time (BTW, org+latex=awesomness!).

I'll use the abstract as example, but the same idea is valid for other
semantic markup like front, main and backmatter. 

As a MWE let's see this org file.

--8<---------------cut here---------------start------------->8---
[some latex preamble]

* Abstract

The abstract body text (even with some level 2 headers in the middle).

* Process

** A level 2 header

It's body text and the rest of the report... 
--8<---------------cut here---------------end--------------->8---

When this is exported to latex (using a slightly modified memoir class),
the 1st header has "Abstract" as title, but doesn't express that it *is*
an abstract. So, for example, it can be styled, or it can be searched
inside specifically. 

The org manual(1), says:

... place the abstract and #+LATEX: commands for frontmatter before the
first exported headline, e.g.,
#+BEGIN_abstract
  [Abstract here]
#+END_abstract

The question is: how do I use the 1st header (keeping it's folding and
referencing in org) while at the same time expressing that it is an
abstract? How (if) can be done not only before the ToC, LoF and LoT but
after them? 

I already tried this, without success:

--8<---------------cut here---------------start------------->8---
[some latex preamble]

* Abstract
#+BEGIN_abstract

The abstract body text (even with some level 2 headers in the middle).

#+END_abstract

* Process

It's body text and the rest of the report... 
--8<---------------cut here---------------end--------------->8---


Is there is no mechanism yet (which I doubt) and if it makes sense, is
it possible to use properties for this? Something like:

--8<---------------cut here---------------start------------->8---
[some latex preamble]

* Abstract
:PROPERTIES:
:latex-type:    abstract
:END:

The abstract body text (even with some level 2 headers in the middle).

* Process

It's body text and the rest of the report... 
--8<---------------cut here---------------end--------------->8---

In this way each exporter backend can use that info as it pleases. Latex
to use it's specific markup, html to make a class, etc. 

Please forgive me if the answer is obvious, but I've searched and found
nothing. I did my homework and I'm sure it's there, but obviously I'm
not searching with the appropiate keywords.

As always, thank you in advance for sharing your time and experience. :)

Best...



(1) http://orgmode.org/worg/org-tutorials/org-latex-export.html#orgheadline17
-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Thomas S. Dye]

Aloha Eduardo,

You might find Aaron Ecay's ox-extra.el in contrib useful.  It defines
an :ignore: tag that instructs the exporter to ignore the headline it
tags, but still export the text, etc. under the headline.

So,

,----------------------------
| * Abstract         :ignore:
|                            
| #+begin_abstract           
| The abstract ...           
| #+end_abstract             
|                            
| * Chapter 1                
`----------------------------

will give you an abstract before Chapter 1 and you'll still be able to
fold it out of the way when you don't want to see it.

hth,
Tom

Eduardo Mercovich writes:

> Dear all.
>
> I'm using org-mode as a writer and it is simply fantastic. One of the
> things I enjoy more is the folding. A huge report like the one I'm
> working on seems sooo easy... ;)
>
> However, I don't know how to integrate that with some semantic markup
> and the latex exporter at the same time (BTW, org+latex=awesomness!).
>
> I'll use the abstract as example, but the same idea is valid for other
> semantic markup like front, main and backmatter. 
>
> As a MWE let's see this org file.
>
> --8<---------------cut here---------------start------------->8---
> [some latex preamble]
>
> * Abstract
>
> The abstract body text (even with some level 2 headers in the middle).
>
> * Process
>
> ** A level 2 header
>
> It's body text and the rest of the report... 
> --8<---------------cut here---------------end--------------->8---
>
> When this is exported to latex (using a slightly modified memoir class),
> the 1st header has "Abstract" as title, but doesn't express that it *is*
> an abstract. So, for example, it can be styled, or it can be searched
> inside specifically. 
>
> The org manual(1), says:
>
> ... place the abstract and #+LATEX: commands for frontmatter before the
> first exported headline, e.g.,
> #+BEGIN_abstract
>   [Abstract here]
> #+END_abstract
>
> The question is: how do I use the 1st header (keeping it's folding and
> referencing in org) while at the same time expressing that it is an
> abstract? How (if) can be done not only before the ToC, LoF and LoT but
> after them? 
>
> I already tried this, without success:
>
> --8<---------------cut here---------------start------------->8---
> [some latex preamble]
>
> * Abstract
> #+BEGIN_abstract
>
> The abstract body text (even with some level 2 headers in the middle).
>
> #+END_abstract
>
> * Process
>
> It's body text and the rest of the report... 
> --8<---------------cut here---------------end--------------->8---
>
>
> Is there is no mechanism yet (which I doubt) and if it makes sense, is
> it possible to use properties for this? Something like:
>
> --8<---------------cut here---------------start------------->8---
> [some latex preamble]
>
> * Abstract
> :PROPERTIES:
> :latex-type:    abstract
> :END:
>
> The abstract body text (even with some level 2 headers in the middle).
>
> * Process
>
> It's body text and the rest of the report... 
> --8<---------------cut here---------------end--------------->8---
>
> In this way each exporter backend can use that info as it pleases. Latex
> to use it's specific markup, html to make a class, etc. 
>
> Please forgive me if the answer is obvious, but I've searched and found
> nothing. I did my homework and I'm sure it's there, but obviously I'm
> not searching with the appropiate keywords.
>
> As always, thank you in advance for sharing your time and experience. :)
>
> Best...
>
>
>
> (1) http://orgmode.org/worg/org-tutorials/org-latex-export.html#orgheadline17


-- 
Thomas S. Dye
http://www.tsdye.com

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Aloha Tom. 

>> I'm using org-mode as a writer and it is simply fantastic. One of the
>> things I enjoy more is the folding. [...]
>> However, I don't know how to integrate that with some semantic markup
>> and the latex exporter at the same time (BTW, org+latex=awesomness!).
>> I'll use the abstract as example, but the same idea is valid for other
>> semantic markup like front, main and backmatter. [...]

> You might find Aaron Ecay's ox-extra.el in contrib useful.  It defines
> an :ignore: tag that instructs the exporter to ignore the headline it
> tags, but still export the text, etc. under the headline.
> ,----------------------------
> | * Abstract         :ignore:
> |                            
> | #+begin_abstract           
> | The abstract ...           
> | #+end_abstract             
> |                            
> | * Chapter 1                
> `----------------------------
>
> will give you an abstract before Chapter 1 and you'll still be able to
> fold it out of the way when you don't want to see it.

That's exactly what I've been searching for.

Thank you! :D

Best...


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Christian Moe]

Eduardo Mercovich writes:
>
> ... place the abstract and #+LATEX: commands for frontmatter before the
> first exported headline, e.g.,
> #+BEGIN_abstract
>   [Abstract here]
> #+END_abstract

Originally my fault for pointing out that this was possible (for latex
and html backends, anyway) without any special abstract handling. :-)

https://lists.gnu.org/archive/html/emacs-orgmode/2010-11/msg00046.html

> The question is: how do I use the 1st header (keeping it's folding and
> referencing in org) while at the same time expressing that it is an
> abstract?

One can fold a block manually. However, it won't be automatically folded
when a file is opened or when when cycling the whole buffer through
folding states with C-u TAB. If these matter to you (I gather that you
have to write long abstracts), you may need to use the ignore trick
Thomas Dye referred to.

You can name a block and reference it by name.

#+name: theabstract
#+begin_abstract
  ...
#+end_abstract

See [[theabstract][the abstract]].

> How (if) can be done not only before the ToC, LoF and LoT but
> after them? 

You can control placement with a #+TOC: line. Do you need to do
something more?

An OS X upgrade just nuked my unix toolchains, including latex, so I
haven't checked how things work there.

Yours,
Christian

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Hi Christian. 

>> ... place the abstract and #+LATEX: commands for frontmatter before the
>> first exported headline, e.g.,
>> #+BEGIN_abstract
>>   [Abstract here]
>> #+END_abstract

> Originally my fault for pointing out that this was possible (for latex
> and html backends, anyway) without any special abstract handling. :-)
> https://lists.gnu.org/archive/html/emacs-orgmode/2010-11/msg00046.html

No fault at all, on the contrary. This collective knowledge is built by
everyone that participates. :)

> [...] If these matter to you (I gather that you have to write long
> abstracts), you may need to use the ignore trick Thomas Dye referred
> to.

I'll do, as that solution has the best of both worlds. :)

> You can name a block and reference it by name.
> #+name: theabstract
> #+begin_abstract
>   ...
> #+end_abstract
> See [[theabstract][the abstract]].

This linking capacity is great and I'm using it a lot.

The only detail remaining here that I'm still searching is how to
include the table/figure # also with the link. This is because if
someone prints the report, the link becomes unusable without a number.

An example would be:

--8<---------------cut here---------------start------------->8---
Lorem ipsum... 

#+CAPTION: A beautiful caption for this table. 
#+NAME: table:tablename
#+ATTR_LATEX: :environment longtable
[the table]

A lot of text, going pages long.

In this paragraph, there is a [[tablename][link to the table]]. 
--8<---------------cut here---------------end--------------->8---

This renders the link perfectly, but in the linked text <link to the
table> there is no further reference. How can the (automagically added)
number be included, like in <link to the table #12)?

Just for the sake of making it ultra complete (I don't feel it necessary
really), the link could use the id only to point, and be rendered as
<table # (page N)>.

I'm sure it's there but even having read the manual I still lack the
emacspeak to find it, or maybe to understand that I already read over
it. :)

Anyway, Have a great day... 


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Eric S Fraga]

On Thursday, 31 Mar 2016 at 21:39, Eduardo Mercovich wrote:

[...]

> This linking capacity is great and I'm using it a lot.
>
> The only detail remaining here that I'm still searching is how to
> include the table/figure # also with the link. This is because if
> someone prints the report, the link becomes unusable without a number.

Well, if you are exporting to LaTeX, the easiest thing to do is not put
a description in the link, e.g.: see the results in Table
[[tablename]].  This will export as a number in LaTeX export.
-- 
: Eric S Fraga (0xFFFCF67D), Emacs 25.0.92.1, Org release_8.3.4-668-g809a83

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Hi Eric. 

>> This linking capacity is great and I'm using it a lot.
>> The only detail remaining here that I'm still searching is how to
>> include the table/figure # also with the link. This is because if
>> someone prints the report, the link becomes unusable without a number.

> Well, if you are exporting to LaTeX, the easiest thing to do is not put
> a description in the link, e.g.: see the results in Table
> [[tablename]].  This will export as a number in LaTeX export.

Thank you very much. I didn't knew that leaving the text undefined would
render the number. :)

As always, thank you very much.

I hope to be able to give back in the future. :)

Best...


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Adam Porter]

Hi Eduardo,

Just a note, you mentioned that you find the folding very useful, so you
might want to try out the org-tree-to-indirect-buffer command.  It's very
helpful when you're working on a large Org file and only want to work on
certain parts of it.  I don't see it mentioned often, so I'm not sure many
people are aware of it (there's always something else to learn about Org!).

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Hi Adam. 

> Just a note, you mentioned that you find the folding very useful, so you
> might want to try out the org-tree-to-indirect-buffer command.  It's very
> helpful when you're working on a large Org file and only want to work on
> certain parts of it. [...]

I didn't knew it, thank you. :)
Also less known that it deserves, for focusing I do use narrowing a lot:

C-x n s     (org-narrow-to-subtree)
    Narrow buffer to current subtree. 

C-x n w     (widen)
    Widen buffer to remove narrowing.

(more in http://orgmode.org/manual/Structure-editing.html)

Thanks again. :)
Best...


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Adam Porter]

Eduardo Mercovich <eduardo <at> mercovich.net> writes:

> Also less known that it deserves, for focusing I do use narrowing a lot:

Yeah, that's basically what tree-to-indirect does, it makes an indirect
buffer and then narrows it.  So you can widen the indirect buffer and get
another view of the whole buffer.  

I also use this advice to rename the indirect buffer to the name of the
heading, that way you don't end up with "file.org<1>"-style buffers:

(defun ap/org-rename-tree-to-indirect-buffer (&rest args)
    "Rename the new buffer to the current org heading after using
org-tree-to-indirect-buffer."
    (with-current-buffer (car (buffer-list (car (frame-list))))
      (save-excursion
        (let* ((heading (nth 4 (org-heading-components)))
               (name (if (string-match org-bracket-link-regexp heading)
                         ;; Heading is an org link; use link name
                         ;; TODO: but what if only part of the heading is?
                         (match-string 3 heading)
                       ;; Not a link; use whole heading
                       heading)))
          (rename-buffer name) t))))
  (advice-add 'org-tree-to-indirect-buffer :after
'ap/org-rename-tree-to-indirect-buffer)

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Hi Adam.

>> Also less known that it deserves, for focusing I do use narrowing a
>> lot: [...]

> Yeah, that's basically what tree-to-indirect does, it makes an indirect
> buffer and then narrows it.  So you can widen the indirect buffer and get
> another view of the whole buffer. [...]

Excuse me if this sounds almost philosophical, but in which situation an
indirect buffer may be better that just focusing on the same (original)
buffer? For example, when you are toying with potentially big
modifications and don't want to replace the original? Is it like opening
a parallel path to try things without worries?

I know it's far from the original question, but it seems interesting to
understand the possibilities. :)


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Nick Dokos]

Eduardo Mercovich <eduardo@mercovich.net> writes:

> Hi Adam.
>
>>> Also less known that it deserves, for focusing I do use narrowing a
>>> lot: [...]
>
>> Yeah, that's basically what tree-to-indirect does, it makes an indirect
>> buffer and then narrows it.  So you can widen the indirect buffer and get
>> another view of the whole buffer. [...]
>
> Excuse me if this sounds almost philosophical, but in which situation an
> indirect buffer may be better that just focusing on the same (original)
> buffer? For example, when you are toying with potentially big
> modifications and don't want to replace the original? Is it like opening
> a parallel path to try things without worries?
>
No - if you change the indirect buffer, you change the base buffer as
well. See

(info "(elisp) Indirect buffers")

For some uses, see

  https://www.emacswiki.org/emacs/IndirectBuffers
  
--
nick

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Hi Nick.

[...]
>> Excuse me if this sounds almost philosophical, but in which situation an
>> indirect buffer may be better that just focusing on the same (original)
>> buffer? For example, when you are toying with potentially big
>> modifications and don't want to replace the original? Is it like opening
>> a parallel path to try things without worries?

> No - if you change the indirect buffer, you change the base buffer as
> well.

As always, razor sharp precise.

Thanks. :)

Best...


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.

Re: How to do proper folding and semantic markup

[Adam Porter]

Eduardo Mercovich <eduardo <at> mercovich.net> writes:

> Excuse me if this sounds almost philosophical, but in which situation an
> indirect buffer may be better that just focusing on the same (original)
> buffer? For example, when you are toying with potentially big
> modifications and don't want to replace the original? Is it like opening
> a parallel path to try things without worries?
> 
> I know it's far from the original question, but it seems interesting to
> understand the possibilities. :)

An excellent question.  :)  I've been thinking about writing an article or
something about this, but I'll give a quick explanation here.

For years I've used Evernote on an irregular basis (they have been steadily
regressing the UI across all platforms), and one of the things I do like
about it is that each note is independent of the other notes in the
database.  When I'm editing one note, I only see that note, and I can only
change that note.  

In Org, since I keep my notes in a few large files, it means that when I
jump to a heading, I also see all the surrounding headings.  Sometimes
that's what I want, like if I'm editing a document, but when I jump to a
random entry in my inbox.org file, the headings surrounding it are
completely unrelated to the one I'm looking at, and they get in the way.

So by jumping to an entry in an indirect buffer, I see only that entry, and
I can't modify any other nodes.  It means I can treat each entry
independently, view and edit them separately, etc.

In this way it resembles the way Evernote presents notes independently, but
with all the power and flexibility of Org and Emacs.

I put functions in org-bookmark-heading and helm-org-rifle to jump to
entries in indirect buffers by pressing <C-return> (by default), but I also
do this in Agenda views with this code:

  (defun ap/org-agenda-goto-heading-in-indirect-buffer (&optional switch-to)
    "Go to the current agenda headline in an indirect buffer. If SWITCH-TO
is non-nil, close the org-agenda window."
    (interactive)
    (if switch-to
        (org-agenda-switch-to)
      (org-agenda-goto))
    (org-tree-to-indirect-buffer)
  
    ;; Put the non-indirect buffer at the bottom of the prev-buffers
    ;; list so it won't be selected when the indirect buffer is killed
    (set-window-prev-buffers nil (append (cdr (window-prev-buffers))
                                         (car (window-prev-buffers)))))
  
  (defun ap/org-agenda-switch-to-heading-in-indirect-buffer ()
    (interactive)

To me this is a very powerful and flexible way of working with Org files,
one that I think deserves wider exposure.  Org files can be thought of not
only as outlined documents but as collections of individual, unrelated
entries that can be viewed and edited independently.

(I also confess that it gives me some peace of mind, because a few times I
have accidentally hit the wrong keys and deleted parts of an Org file that I
didn't mean to.  Most of the time I immediately undo it and no harm is done,
but one time I didn't realize it until days or weeks later, and I had to
pull it out of an earlier commit in my org directory's git repo.)

Hope this helps!  Let me know if you have any other questions or ideas.  :)

Re: How to do proper folding and semantic markup

[Eduardo Mercovich]

Hi Adam.  Porter <adam@alphapapa.net> writes:

>> Excuse me if this sounds almost philosophical, but in which situation an
>> indirect buffer may be better that just focusing on the same (original)
>> buffer?  [...]

> [...]
> So by jumping to an entry in an indirect buffer, I see only that entry, and
> I can't modify any other nodes.  It means I can treat each entry
> independently, view and edit them separately, etc.

> In this way it resembles the way Evernote presents notes independently, but
> with all the power and flexibility of Org and Emacs. [...]
> (I also confess that it gives me some peace of mind, because a few times I
> have accidentally hit the wrong keys and deleted parts of an Org file that I
> didn't mean to.  Most of the time I immediately undo it and no harm is done,
> but one time I didn't realize it until days or weeks later, and I had to
> pull it out of an earlier commit in my org directory's git repo.)

Crystal clear, thanks. :)
Best...


-- 
eduardo mercovich 

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación.