From mboxrd@z Thu Jan 1 00:00:00 1970 From: Diego Zamboni Subject: =?UTF-8?B?UmU6IOKAnExpdGVyYXRl4oCdIHB5dGhvbj8=?= Date: Fri, 29 Nov 2019 23:32:09 +0100 Message-ID: References: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="00000000000089a5b2059883cdc3" Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:58178) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iaooK-0003an-E7 for emacs-orgmode@gnu.org; Fri, 29 Nov 2019 17:32:26 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iaooI-0004a5-HW for emacs-orgmode@gnu.org; Fri, 29 Nov 2019 17:32:24 -0500 Received: from mail-wr1-x42d.google.com ([2a00:1450:4864:20::42d]:41268) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iaooI-0004Z1-0e for emacs-orgmode@gnu.org; Fri, 29 Nov 2019 17:32:22 -0500 Received: by mail-wr1-x42d.google.com with SMTP id b18so36885600wrj.8 for ; Fri, 29 Nov 2019 14:32:21 -0800 (PST) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Norman Walsh Cc: Org-mode --00000000000089a5b2059883cdc3 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi Norm, As George said, the trick in this case is to use the =3D:noweb=3D and =3D:noweb-ref=3D headers. The change is minimal from the script you sent: #+TITLE: Python literate programming #+OPTIONS: html-postamble:nil It starts off as a completely standard Python3 program. #+BEGIN_SRC python :tangle yes :weave no #!/usr/bin/env python3 #+END_SRC It defines ~a~. #+BEGIN_SRC python :tangle yes def a(): print("a") #+END_SRC And ~b~. #+BEGIN_SRC python :tangle yes def b(): print("b") #+END_SRC Now ~c~ is a little more complicated: #+BEGIN_SRC python :tangle yes :noweb no-export def c(): print("c") <> #+END_SRC Not only does ~c~ print =E2=80=9Cc=E2=80=9D, it calls ~a()~ and ~b()~. #+BEGIN_SRC python :tangle no :noweb-ref call-a-and-b b() a() #+END_SRC Finally, make it importable. Not that you=E2=80=99d want to. #+BEGIN_SRC python :tangle yes if __name__ =3D=3D "__main__": main() #+END_SRC Note the =3D:noweb no-export=3D in the block that contains =3Ddef c()=3D. T= he =3Dno-export=3D value makes it so that, on HTML export, the noweb reference= is shown as a reference instead of expanded (which is usually what you want). The next block is given its name using the =3D:noweb-ref=3D header argument= . You could also use =3D#+name:=3D - the main difference is that =3D:noweb-re= f=3D allows you to have multiple blocks with the same name, which are concatenated together when tangled, whereas =3D#+name:=3D only allows one b= lock with the same name. If I may do a bit of self-promotion, feel free to check out my "Literate Config" booklet, which I published just a few days ago (available for free) and which contains some more tips for doing literate programming: https://leanpub.com/lit-config/read Best, --Diego On Fri, Nov 29, 2019 at 7:09 PM Norman Walsh wrote: > Hi, > > I=E2=80=99ve seen a couple of pointers recently to using Org mode and tan= gle > to write more literate Emacs configurations. I use Org+babel all the > time to write =E2=80=9Cinteractive=E2=80=9D documents, so I thought I=E2= =80=99d try out tangle > from Org. > > I didn=E2=80=99t want to start with something as comlicated as my Emacs > config :-) so I figured I=E2=80=99d kick the tires with a small python > program. That did not end well. > > Consider: > > #+TITLE: Python literate programming > #+OPTIONS: html-postamble:nil > > It starts off as a completely standard Python3 program. > > ---%<------------------------------------------------------ > #+BEGIN_SRC python :tangle yes :weave no > #!/usr/bin/env python3 > > #+END_SRC > > It defines ~a~. > > #+BEGIN_SRC python :tangle yes > def a(): > print("a") > > > #+END_SRC > > And ~b~. > > #+BEGIN_SRC python :tangle yes > def b(): > print("b") > > > #+END_SRC > > Now ~c~ is a little more complicated: > > #+BEGIN_SRC python :tangle yes > def c(): > print("c") > #+END_SRC > > Not only does ~c~ print =E2=80=9Cc=E2=80=9D, it calls ~a()~ and ~b()~. > > #+BEGIN_SRC python :tangle yes > b() > a() > #+END_SRC > > Finally, make it importable. Not that you=E2=80=99d want to. > > #+BEGIN_SRC python :tangle yes > if __name__ =3D=3D "__main__": > main() > #+END_SRC > --->%------------------------------------------------------ > > That=E2=80=99s the script. It weaves into HTML more-or-less ok (there=E2= =80=99s a > weird black box at the front of indented lines, but I can come back to > that later). > > It=E2=80=99s a complete mess when tangled. > > The extra blank lines between functions (to make pylint happy with > some PEP guideline) have disappeared. I guess I could live with that, > but the complete failure to preserve indention in the penultimate code > block is a show stopper: > > #!/usr/bin/env python3 > > def a(): > print("a") > > def b(): > print("b") > > def c(): > print("c") > > b() > a() > > if __name__ =3D=3D "__main__": > main() > > (Also, why is there an extra blank line before the incorrectly > indented block?) > > Is this user error on my part somehow? I suppose I could write my own > version of tangle, though I=E2=80=99m not clear if the whitespace is lost= in > the tangle function or in the Org mode data model. > > Thoughts? > > Be seeing you, > norm > > -- > Norman Walsh | We discover in ourselves what others > http://nwalsh.com/ | hide from us, and we recognize in > | others what we hide from > | ourselves.--Vauvenargues > --00000000000089a5b2059883cdc3 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Norm,

As George said, the trick in t= his case is to use the =3D:noweb=3D and =3D:noweb-ref=3D headers. The chang= e is minimal from the script you sent:

#+TITLE: Py= thon literate programming
#+OPTIONS: html-postamble:nil

It starts= off as a completely standard Python3 program.

#+BEGIN_SRC python :t= angle yes :weave no
#!/usr/bin/env python3
#+END_SRC

It define= s ~a~.

#+BEGIN_SRC python :tangle yes
def a():
=C2=A0 =C2=A0 p= rint("a")

#+END_SRC

And ~b~.

#+BEGIN_SRC pyt= hon :tangle yes
def b():
=C2=A0 =C2=A0 print("b")

#+= END_SRC

Now ~c~ is a little more complicated:

#+BEGIN_SRC pyt= hon :tangle yes :noweb no-export
def c():
=C2=A0 =C2=A0print("c&= quot;)
=C2=A0 =C2=A0<<call-a-and-b>>
#+END_SRC

Not= only does ~c~ print =E2=80=9Cc=E2=80=9D, it calls ~a()~ and ~b()~.

= #+BEGIN_SRC python :tangle no :noweb-ref call-a-and-b
=C2=A0 =C2=A0b()=C2=A0 =C2=A0a()
#+END_SRC

Finally, make it importable. Not tha= t you=E2=80=99d want to.

#+BEGIN_SRC python :tangle yes
if __name= __ =3D=3D "__main__":
=C2=A0 =C2=A0 main()
#+END_SRC

Note the =3D:noweb no-export=3D in the block that co= ntains =3Ddef c()=3D. The =3Dno-export=3D value makes it so that, on HTML e= xport, the noweb reference is shown as a reference instead of expanded (whi= ch is usually what you want). The next block is given its name using the = =3D:noweb-ref=3D header argument. You could also use =3D#+name:=3D - the ma= in difference is that =3D:noweb-ref=3D allows you to have multiple blocks w= ith the same name, which are concatenated together when tangled, whereas = =3D#+name:=3D only allows one block with the same name.

If I may do a bit of self-promotion, feel free to check out my "= Literate Config" booklet, which I published just a few days ago (avail= able for free) and which contains some more tips for doing literate program= ming:=C2=A0https://leanpub.= com/lit-config/read

Best,
--Diego


On Fri, Nov 29, 2019 at 7:09 PM Norman Walsh <ndw@nwalsh.com> wrote:
Hi,

I=E2=80=99ve seen a couple of pointers recently to using Org mode and tangl= e
to write more literate Emacs configurations. I use Org+babel all the
time to write =E2=80=9Cinteractive=E2=80=9D documents, so I thought I=E2=80= =99d try out tangle
from Org.

I didn=E2=80=99t want to start with something as comlicated as my Emacs
config :-) so I figured I=E2=80=99d kick the tires with a small python
program. That did not end well.

Consider:

#+TITLE: Python literate programming
#+OPTIONS: html-postamble:nil

It starts off as a completely standard Python3 program.

---%<------------------------------------------------------
#+BEGIN_SRC python :tangle yes :weave no
#!/usr/bin/env python3

#+END_SRC

It defines ~a~.

#+BEGIN_SRC python :tangle yes
def a():
=C2=A0 =C2=A0 print("a")


#+END_SRC

And ~b~.

#+BEGIN_SRC python :tangle yes
def b():
=C2=A0 =C2=A0 print("b")


#+END_SRC

Now ~c~ is a little more complicated:

#+BEGIN_SRC python :tangle yes
def c():
=C2=A0 =C2=A0print("c")
#+END_SRC

Not only does ~c~ print =E2=80=9Cc=E2=80=9D, it calls ~a()~ and ~b()~.

#+BEGIN_SRC python :tangle yes
=C2=A0 =C2=A0b()
=C2=A0 =C2=A0a()
#+END_SRC

Finally, make it importable. Not that you=E2=80=99d want to.

#+BEGIN_SRC python :tangle yes
if __name__ =3D=3D "__main__":
=C2=A0 =C2=A0 main()
#+END_SRC
--->%------------------------------------------------------

That=E2=80=99s the script. It weaves into HTML more-or-less ok (there=E2=80= =99s a
weird black box at the front of indented lines, but I can come back to
that later).

It=E2=80=99s a complete mess when tangled.

The extra blank lines between functions (to make pylint happy with
some PEP guideline) have disappeared. I guess I could live with that,
but the complete failure to preserve indention in the penultimate code
block is a show stopper:

#!/usr/bin/env python3

def a():
=C2=A0 =C2=A0 print("a")

def b():
=C2=A0 =C2=A0 print("b")

def c():
=C2=A0 =C2=A0print("c")

b()
a()

if __name__ =3D=3D "__main__":
=C2=A0 =C2=A0 main()

(Also, why is there an extra blank line before the incorrectly
indented block?)

Is this user error on my part somehow? I suppose I could write my own
version of tangle, though I=E2=80=99m not clear if the whitespace is lost i= n
the tangle function or in the Org mode data model.

Thoughts?

=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 Be seein= g you,
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 n= orm

--
Norman Walsh <ndw@nw= alsh.com> | We discover in ourselves what others
http://= nwalsh.com/=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | hide from us, an= d we recognize in
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | others what we hide from
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | ourselves.--Vauvenargues
--00000000000089a5b2059883cdc3--