emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Spelled out example of org-latex-format-headline-function customization?
@ 2013-03-19  2:56 John Hendy
  2013-03-19 15:51 ` Bastien
  0 siblings, 1 reply; 5+ messages in thread
From: John Hendy @ 2013-03-19  2:56 UTC (permalink / raw)
  To: emacs-orgmode

Like this post, I'm trying to transfer over my tag formatting for
LaTeX export into the new exporter:
- http://www.mail-archive.com/emacs-orgmode@gnu.org/msg65287.html

In that post, the following is suggested:

#+begin_quote Charles Berry

M-x customize-variable RET org-latex-format-headline-function RET

then copy and paste the last part of the docstring into the window - add a
closing parenthesis at the end - and then modify it to your taste.

#+end_quote

When I do that, however, I get this in the customize buffer:

#+begin_src customize buffer
Hide Org Latex Format Headline Function:
org-latex-format-headline-default-function
   State : STANDARD.
   Function for formatting the headline's text. Hide

   This function will be called with 5 arguments:
   TODO      the todo keyword (string or nil).
   TODO-TYPE the type of todo (symbol: `todo', `done', nil)
   PRIORITY  the priority of the headline (integer or nil)
   TEXT      the main headline text (string).
   TAGS      the tags as a list of strings (list of strings or nil).

   The function result will be used in the section format string.

   Use `org-latex-format-headline-default-function' by default,
   which format headlines like for Org version prior to 8.0.

#+end_src

Am I missing the "docstring" (not sure what that is). I think it would
be wonderful to simply spell out what
=org-latex-format-headline-default-function= *is* in plain language,
in the customize buffer.

ETA: perhaps the plain language docstring used to be there, but was
then replaced with a function?
- http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg01306.html

In looking through ox-latex.el, I found this:

#+begin_src ox-latex.el

(concat
   (and todo (format "{\\bfseries\\sffamily %s} " todo))
   (and priority (format "\\framebox{\\#%c} " priority))
   text
   (and tags
        (format "\\hfill{}\\textsc{%s}" (mapconcat 'identity tags ":")))))

#+end_src

For myself, not being familiar with elisp, it's unclear how to
translate that to a variable setting. I'm thinking at least some of
that is unnecessary for actually setting the variable. If not, my best
guess was:

#+begin_src .emacs

(setq org-latex-format-headline-function (concat
   (and todo (format "{\\bfseries\\sffamily %s} " todo))
   (and priority (format "\\framebox{\\#%c} " priority))
   text
   (and tags
        (format "\\hfill{}\\textsc{%s}" (mapconcat 'identity tags ":")))))

#+end_src

That didn't work.


Thanks for enduring those of us with no elisp background knowledge.


Best regards,
John

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Spelled out example of org-latex-format-headline-function customization?
  2013-03-19  2:56 Spelled out example of org-latex-format-headline-function customization? John Hendy
@ 2013-03-19 15:51 ` Bastien
  2013-03-19 16:18   ` John Hendy
  0 siblings, 1 reply; 5+ messages in thread
From: Bastien @ 2013-03-19 15:51 UTC (permalink / raw)
  To: John Hendy; +Cc: emacs-orgmode

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

> Am I missing the "docstring" (not sure what that is). 

The "docstring" is the documentation string attached to a
function/command or a variable/option.

C-h v org-latex-format-headline-function RET 

will show you the docstring of the variable.

C-h f org-latex-format-headline-default-function RET 

will show you the docstring of the function.

> I think it would
> be wonderful to simply spell out what
> =org-latex-format-headline-default-function= *is* in plain language,
> in the customize buffer.
>
> ETA: perhaps the plain language docstring used to be there, but was
> then replaced with a function?
> - http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg01306.html

Yes, that's the case.

> In looking through ox-latex.el, I found this:
>
> #+begin_src ox-latex.el
>
> (concat
>    (and todo (format "{\\bfseries\\sffamily %s} " todo))
>    (and priority (format "\\framebox{\\#%c} " priority))
>    text
>    (and tags
>         (format "\\hfill{}\\textsc{%s}" (mapconcat 'identity tags ":")))))
>
> #+end_src
>
> For myself, not being familiar with elisp, it's unclear how to
> translate that to a variable setting. I'm thinking at least some of
> that is unnecessary for actually setting the variable. If not, my best
> guess was:
>
> #+begin_src .emacs
>
> (setq org-latex-format-headline-function (concat
>    (and todo (format "{\\bfseries\\sffamily %s} " todo))
>    (and priority (format "\\framebox{\\#%c} " priority))
>    text
>    (and tags
>         (format "\\hfill{}\\textsc{%s}" (mapconcat 'identity tags ":")))))
>
> #+end_src
>
> That didn't work.

You need to 

1) define a new function

(defun john-org-latex-headline-function (todo todo-type priority text tags)
  "The docstring of my function."
  (concat
   (and todo (format "{\\bfseries\\sffamily %s} " todo))
   (and priority (format "\\framebox{\\#%c} " priority))
   text
   (and tags
	(format "\\hfill{}\\textsc{%s}" (mapconcat 'identity tags ":")))))


The function has 5 arguments : todo todo-type priority text tags

All these arguments are strings that you can manipulate in your
own function.  

E.g., 

  (and todo (format "{\\bfseries\\sffamily %s} " todo))

translates "If the todo argument has a value, then let's format 
the string "{\\bfseries\\sffamily %s} " by replacing %s with the
todo string.  Which results in e.g. "{\bfseries\sffamily TODO} "

Inside formatting strings, you need to escape the \ character,
i.e. to prepend it with another \ char.

> Thanks for enduring those of us with no elisp background knowledge.

That's actually an area where I think we should make things simple.
Nicolas and I have been exchanging a few ideas, but nothing stable 
emerges yet. 

Best,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Spelled out example of org-latex-format-headline-function customization?
  2013-03-19 15:51 ` Bastien
@ 2013-03-19 16:18   ` John Hendy
  2013-03-19 16:30     ` Charles Berry
  2013-03-19 16:37     ` Bastien
  0 siblings, 2 replies; 5+ messages in thread
From: John Hendy @ 2013-03-19 16:18 UTC (permalink / raw)
  To: Bastien; +Cc: emacs-orgmode

On Tue, Mar 19, 2013 at 10:51 AM, Bastien <bzg@altern.org> wrote:
> Hi John,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> Am I missing the "docstring" (not sure what that is).
>
> The "docstring" is the documentation string attached to a
> function/command or a variable/option.
>
> C-h v org-latex-format-headline-function RET
>
> will show you the docstring of the variable.

So the docstring is just the documentation definition? (In this case
"Documentation: Function for formatting the headline's text..."?)

>
> C-h f org-latex-format-headline-default-function RET
>
> will show you the docstring of the function.

And in this case: "(org-latex-format-headline-default-function TODO
TODO-TYPE PRIORITY TEXT TAGS)"?

>
>> I think it would
>> be wonderful to simply spell out what
>> =org-latex-format-headline-default-function= *is* in plain language,
>> in the customize buffer.
>>
>> ETA: perhaps the plain language docstring used to be there, but was
>> then replaced with a function?
>> - http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg01306.html
>
> Yes, that's the case.

Got it. So the docstring is of no use unless you know how to write the
function from scratch.

<snip>

>> That didn't work.
>
> You need to
>
> 1) define a new function

<snip>

Sounds good and this was Nick's instruction as well. Thanks for the assistance!

>
> That's actually an area where I think we should make things simple.
> Nicolas and I have been exchanging a few ideas, but nothing stable
> emerges yet.
>

Good to know. It seems that variables *could* be passed to the format
function. After all, the function takes five arguments which are all
either strings or nil... so it would seem that one could have a
variable like:

(setq org-latex-headline-format ("string" "string" "string" "string"
"string")) which would feed into the default-headline-function
function.

Or splitting out into separate variables. Seems like the tension is
between minimizing locations to make all of these settings and ease of
use (for noobs).


Thanks for all the efforts!
John

> Best,
>
> --
>  Bastien

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Spelled out example of org-latex-format-headline-function customization?
  2013-03-19 16:18   ` John Hendy
@ 2013-03-19 16:30     ` Charles Berry
  2013-03-19 16:37     ` Bastien
  1 sibling, 0 replies; 5+ messages in thread
From: Charles Berry @ 2013-03-19 16:30 UTC (permalink / raw)
  To: emacs-orgmode

John Hendy <jw.hendy <at> gmail.com> writes:

> 
> On Tue, Mar 19, 2013 at 10:51 AM, Bastien <bzg <at> altern.org> wrote:
> > Hi John,
> >
> > John Hendy <jw.hendy <at> gmail.com> writes:
> >
> >> Am I missing the "docstring" (not sure what that is).

THAT docstring was removed when Bastien revised ox-latex.el on Feb 23.

So follow what Bastien posts in this thread to do the customization.

I'll add a note to my earlier post to point here.

> >
> > The "docstring" is the documentation string attached to a
> > function/command or a variable/option.
> >
> > C-h v org-latex-format-headline-function RET
> >
> > will show you the docstring of the variable.
> 


HTH,

Chuck

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Spelled out example of org-latex-format-headline-function customization?
  2013-03-19 16:18   ` John Hendy
  2013-03-19 16:30     ` Charles Berry
@ 2013-03-19 16:37     ` Bastien
  1 sibling, 0 replies; 5+ messages in thread
From: Bastien @ 2013-03-19 16:37 UTC (permalink / raw)
  To: John Hendy; +Cc: emacs-orgmode

John Hendy <jw.hendy@gmail.com> writes:

> So the docstring is just the documentation definition? (In this case
> "Documentation: Function for formatting the headline's text..."?)

Yes.

>> C-h f org-latex-format-headline-default-function RET
>>
>> will show you the docstring of the function.
>
> And in this case: "(org-latex-format-headline-default-function TODO
> TODO-TYPE PRIORITY TEXT TAGS)"?

Not exactly... Emacs display the documentation after the definition of
the function and its arguments.

The definition here is:

  Default format function for a headline.
  See `org-latex-format-headline-function' for details.

> Good to know. It seems that variables *could* be passed to the format
> function. After all, the function takes five arguments which are all
> either strings or nil... so it would seem that one could have a
> variable like:
>
> (setq org-latex-headline-format ("string" "string" "string" "string"
> "string")) which would feed into the default-headline-function
> function.
>
> Or splitting out into separate variables. Seems like the tension is
> between minimizing locations to make all of these settings and ease of
> use (for noobs).

This is what our discussion with Nicolas is really about.
There are problems with tags, though: you need to handle them
one by one, not as a string.

I'll send news if any!

-- 
 Bastien

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2013-03-19 16:37 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-03-19  2:56 Spelled out example of org-latex-format-headline-function customization? John Hendy
2013-03-19 15:51 ` Bastien
2013-03-19 16:18   ` John Hendy
2013-03-19 16:30     ` Charles Berry
2013-03-19 16:37     ` Bastien

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).