Seeking advice for conditional code

Seeking advice for conditional code

[François Pinard]

Hi, Org friends.

Would someone be kind enough to point me in the right direction, if
there is one already?  My need is to have conditional code at
publication time, and being able to include or exclude regions of code
according to some symbol being "active" or "defined", or not.

The use case is a piece of Python code implementing an API interface,
for which items are implemented through functions (methods).  These
functions each have a doc-string, using Org, documenting that item.
Now, there are API items which we publish for our users, and other API
items which are rather internal and which we would not document
externally.  I would much prefer keeping a single source, and generate
different documentation for the external site and the internal site.

Currently, I use poporg (https://github.com/pinard/poporg) to edit these
doc-strings, and a small program which reads and concatenate them all.
This program already recognizes #+FILE: (not Org standard) to drive the
splitting of the resulting Org document into many files, each of which
will end up being an HTML page.  The first idea which comes to my mind
is adding #+IF: #+ELIF: #+ELSE #+ENDIF directives for that program to
recognize as well.

But if possible, I would much prefer to stick to known and standard Org
paradigms than inventing my own, and this is why I'm asking here...

Keep happy, all!

François

Re: Seeking advice for conditional code

[John Kitchin]

I think I have done something like this with tags and custom export
lisp code.

Something like:

(let ((org-export-exclude-tags '("supplementary" "noexport")))
     (org-export-as-latex 5))

That allows me to export all sections not tagged by those values. This
would require all your code blocks be in tagged sections, e.g. tagged by
"internal", "external", etc...

for a particular org file I make an init.el file with different export
functions in it. Alternatively, I have put emacs-lisp code blocks in the
org file so it is self contained.

I am curious what other people do. My typical uses for selective export
are to selectively export a manuscript from an org file, or to
separately export a homework and the solution from one file.
-- 
==================================
John Kitchin
Associate Professor
A207F Doherty Hall
Department of Chemical Engineering
Carnegie Mellon University
412-268-7803

Re: Seeking advice for conditional code

[Sebastien Vauban]

Hi François,

François Pinard wrote:
> Would someone be kind enough to point me in the right direction, if
> there is one already?  My need is to have conditional code at
> publication time, and being able to include or exclude regions of code
> according to some symbol being "active" or "defined", or not.

I want to be sure to understand: do you need

- conditional tangled code, or

- conditional "full" document (containing conditional code and conditional
  doc)?

When you say "conditional", do you mean to to be able to decide to include it
or not, or even more (such as including one version or the other)?

What's sure if that you can have conditions based on tags, and things in the
following spirit::

--8<---------------cut here---------------start------------->8---
* Global constants

#+tblname: params
| Variable           | dev | stg | prd |
|--------------------+-----+-----+-----|
| webServerName      | a   | g   | m   |
| loginWebServerName | b   | h   | n   |
| pwWebServerName    | c   | i   | o   |
| appBaseDir         | d   | j   | p   |
| dbName             | e   | k   | q   |
| dbBackupFile       | f   | l   | r   |

* Show the params                                                        :dev:

Params are "dynamically" assigned. Here the results with the "dev" tag:

#+begin_src sh :rownames no :var data=(concat (car (org-get-tags-at (point))) "-params") :exports both
echo $data
#+end_src
--8<---------------cut here---------------end--------------->8---

Please tell if that's more or less the direction you want to take...

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Seeking advice for conditional code

[François Pinard]

"Sebastien Vauban"
<wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> writes:

> Hi François,

Hi, Sebastien! :-)

> Please tell if that's more or less the direction you want to take...

Direction already taken, and completed a few minutes ago! :-).  But I'll
happily revert to something else it if there is a better way to proceed.
The addition of pseudo-Org directives does not really please me, I would
prefer plain Org if possible.  If you are curious, see comments at start
of https://github.com/pinard/poporg/blob/master/extradoc.py.  In my
application, I even define context from the Makefile, which is an
unexpected advantage.

> I want to be sure to understand: do you need
> - conditional tangled code, or
> - conditional "full" document (containing conditional code and conditional
>   doc)?
> When you say "conditional", do you mean to to be able to decide to include it
> or not, or even more (such as including one version or the other)?

Exactly! :-) It's not tangling.  Rather, merely extract the
documentation out of comments found in (program) source code.  The
comments (once removed the hash marks) are in Org format.  I'm seeking
for conditional documentation.

> What's sure if that you can have conditions based on tags, and things in the
> following spirit::
> * Show the params                                                        :dev:
> Params are "dynamically" assigned. Here the results with the "dev" tag:
> #+begin_src sh :rownames no :var data=(concat (car (org-get-tags-at (point))) "-params") :exports both
> echo $data
> #+end_src

I should have thought at exploring the usage of Org tags.  :export: and
:noexport: are already very useful, but the idea did not come to me that I
could extend this to other tags.  I probably do not use tags enough!

In any case, the example above is quite interesting, and could be useful
to solve other problems.  I'll keep it around.

> #+tblname: params
> | Variable           | dev | stg | prd |
> |--------------------+-----+-----+-----|
> | webServerName      | a   | g   | m   |
> | loginWebServerName | b   | h   | n   |
> | pwWebServerName    | c   | i   | o   |
> | appBaseDir         | d   | j   | p   |
> | dbName             | e   | k   | q   |
> | dbBackupFile       | f   | l   | r   |

I missed the point of this table however, I presume the "dev" column is
to be linked in some way to the ":dev:" tag, but I do not see why/how.

> Best regards,

Thanks for caring, Sebastien!  I feel all warm inside :-).

François

Re: Seeking advice for conditional code

[Sebastien Vauban]

Hi François,

François Pinard wrote:
> "Sebastien Vauban" writes:
>> Please tell if that's more or less the direction you want to take...
>
> Direction already taken, and completed a few minutes ago! :-).  But I'll
> happily revert to something else it if there is a better way to proceed.
> The addition of pseudo-Org directives does not really please me, I would
> prefer plain Org if possible.  If you are curious, see comments at start
> of https://github.com/pinard/poporg/blob/master/extradoc.py.  In my
> application, I even define context from the Makefile, which is an
> unexpected advantage.

I'll have a look, but not now... ;-(

>> I want to be sure to understand: do you need
>> - conditional tangled code, or
>> - conditional "full" document (containing conditional code and conditional
>>   doc)?
>> When you say "conditional", do you mean to to be able to decide to include it
>> or not, or even more (such as including one version or the other)?
>
> Exactly! :-) It's not tangling.  Rather, merely extract the
> documentation out of comments found in (program) source code.  The
> comments (once removed the hash marks) are in Org format.  I'm seeking
> for conditional documentation.

For curiosity, why aren't you considering tangling?

>> What's sure if that you can have conditions based on tags, and things in the
>> following spirit::
>> * Show the params                                                        :dev:
>> Params are "dynamically" assigned. Here the results with the "dev" tag:
>> #+begin_src sh :rownames no :var data=(concat (car (org-get-tags-at
>> (point))) "-params") :exports both
>> echo $data
>> #+end_src
>
> I should have thought at exploring the usage of Org tags.  :export: and
> :noexport: are already very useful, but the idea did not come to me that I
> could extend this to other tags.  I probably do not use tags enough!
>
> In any case, the example above is quite interesting, and could be useful
> to solve other problems.  I'll keep it around.
>
>> #+tblname: params
>> | Variable           | dev | stg | prd |
>> |--------------------+-----+-----+-----|
>> | webServerName      | a   | g   | m   |
>> | loginWebServerName | b   | h   | n   |
>> | pwWebServerName    | c   | i   | o   |
>> | appBaseDir         | d   | j   | p   |
>> | dbName             | e   | k   | q   |
>> | dbBackupFile       | f   | l   | r   |
>
> I missed the point of this table however, I presume the "dev" column is
> to be linked in some way to the ":dev:" tag, but I do not see why/how.

The above is almost working real sample -- not had time to really finish it.

The column is a list of parameters (for different environments, such as
"development" machine, "staging" and "production"): paths, user names,
passwords, database names, etc.

By using the tags, you can tangle or display inline code customized to the tag
of their subtree. Have 3 subtrees to list all 3 codes, or have just one, and
change the tag accordingly to what you need to do (generate).

Such a document can be used as a "deployment guideline", for example.

> Thanks for caring, Sebastien!  I feel all warm inside :-).

Silly you ;-)

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Seeking advice for conditional code

[François Pinard]

"Sebastien Vauban"

> For curiosity, why aren't you considering tangling?

Quick half of a reply, I'll revise the rest of your message later.

That would be far too much of a change for the habits of the team, or at
least, this is how I perceive the equilibrium between developers.
Moreover, some of us are not even Emacs users.

When writing a program, the feeling still has to be that we write a
program, rather than a document describing the program, and from which
the program could be extracted.  Python is rather descriptive as a
language, and while comments are useful, they might be less needed than
in other languages.  This is debatable, of course :-).

The documentation is meant for users, and it was strongly suggested that
we try to keep the documentation within the program as much as possible,
as a way to ease keeping the documentation and the program in good
sync.  Some of us really enjoy Org mode, and this is how came the idea
of this compromise of writing Python doc-strings using Org.

François

Re: Seeking advice for conditional code

[Sebastien Vauban]

Hi François,

François Pinard wrote:
> "Sebastien Vauban"
>
>> For curiosity, why aren't you considering tangling?
>
> Quick half of a reply, I'll revise the rest of your message later.
>
> That would be far too much of a change for the habits of the team, or at
> least, this is how I perceive the equilibrium between developers.

OK, you're not alone on that. This explains that.

All I now write (be it SQL, Bash, AWK scripts or ...) is d'office LP'ed, but I
have the chance to be alone on that. Convincing others may prove to be (too)
difficult.

> Moreover, some of us are not even Emacs users.

That's not a real show-stopper per se, as you could tangle code with markers
(via the "comments" parameter), so that the source code could be directly
edited by anyone, and later untangled (that is, written back in your "full
document").

> When writing a program, the feeling still has to be that we write a
> program, rather than a document describing the program, and from which
> the program could be extracted.  Python is rather descriptive as a
> language, and while comments are useful, they might be less needed than
> in other languages.  This is debatable, of course :-).
>
> The documentation is meant for users, and it was strongly suggested that
> we try to keep the documentation within the program as much as possible,
> as a way to ease keeping the documentation and the program in good
> sync.  Some of us really enjoy Org mode, and this is how came the idea
> of this compromise of writing Python doc-strings using Org.

"My" answer:

    #+begin_quote
    Let us change our traditional attitude to the construction of programs:
    Instead of imagining that our main task is to instruct a computer what to
    do, let us concentrate rather on explaining to human beings what we want a
    computer to do.

    The practitioner of literate programming can be regarded as an essayist,
    whose main concern is with exposition and excellence of style. Such an
    author, with thesaurus in hand, chooses the names of variables carefully
    and explains what each variable means. He or she strives for a program
    that is comprehensible because its concepts have been introduced in an
    order that is best for human understanding, using a mixture of formal and
    informal methods that reinforce each other.

    --- Donald Knuth
    #+end_quote

One important aspect here, is that, with LP, you can present your program in
an order which makes sense for the "story". It can be tangled in a totally
different order.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Seeking advice for conditional code

[Eric S Fraga]

Sebastien Vauban <wxhgmqzgwmuf@spammotel.com> writes:

> One important aspect here, is that, with LP, you can present your program in
> an order which makes sense for the "story". It can be tangled in a totally
> different order.

Well said.  This is a subtle point but a very important one!  Combined
with the possibility of tangling different combinations of code, LP is
very liberating.  Org + babel have completely changed how I approach
programming, so much so that I don't know where to start if I have to
write code alone in a non-org file ;-)

-- 
: Eric S Fraga, GnuPG: 0xC89193D8FFFCF67D
: in Emacs 24.3.50.1 and Org release_7.9.3d-898-g005917