Skip to content

Vorg

Jump to bottom Edit New page
Cayetano Santos edited this page Oct 23, 2017 · 19 revisions

Table of Contents

Intro

Following the literate programming paradigm, it is possible to tangle an org-mode file containing source code blocks to a source code file. This helps documenting code, for example, and provides lots of other benefits. An example project following this approach may be found here.

In order to ease handling this workflow, this package defines an ancillary minor mode called vOrg intended to be used along with org major mode. When this minor mode is active, a lighter vOrg will be shown in the mode line.

To auto activate vOrg, one may hook org mode

(add-hook 'org-mode-hook
          (lambda ()
            (when (and (buffer-file-name)
                       (file-exists-p
                        (format "%s.vhd"
                                (file-name-base (buffer-file-name)))))
              (require 'vhdl-tools)
              (vhdl-tools-vorg-mode 1))))

or use file variables in the vOrg file, as for example

-*- mode: vhdl-tools-vorg -*-

Otherwise, it is to be enabled manually.

Features

Jumping around

From an vOrg file, it is possible to tangle its blocks of vhdl source code with help of

C-c C-v t   (vhdl-tools-vorg-tangle)     - tangle vOrg file and beautify resulting buffer
C-c C-v _   (vhdl-tools-vorg-tangle-all) - tangle all vOrg files in current dir and beautify resulting buffers

Additionally, it is also possible to jump from the vOrg file to the vhdl file with help of

C-c M-,     (vhdl-tools-vorg-jump-from-vorg) - jump from vOrg to vhdl

This alternative will implement auto tangling if necessary before jumping.

Then, from within the vhdl source file, and only when the sibling vOrg file exists, it is possible to jump back from the vhdl file to its corresponding vOrg file -assuming its names are identical and only its extension changes- with help of

C-C M-^     (vhdl-tools-vorg-jump-to-vorg) - jump from vhdl to vOrg

Finally, it is also possible to jump from the vOrg file into the vhdl module at point with

C-c M-.     (vhdl-tools-vorg-jump-from-vorg-into-module) - jump from vOrg to module vhdl

Headings

Once vOrg minor mode is active the following keys are made available

C-c C-n     (vhdl-tools-vorg-headings-next)       - get to next header
C-c C-p     (vhdl-tools-vorg-headings-prev)       - get to previous header

Setting vhdl-tools-manage-folding (off by default) to true will allow auto folding upon jumping.

Custom SmartScan

Following the status of the vhdl-tools-remap-smartscan flag (off by default), vOrg will customize the behaviour of smartscan-symbol-go-forward and smartscan-symbol-go-backward, so that they manage folding/unfolding of section headings. This way, upon jumping, only the relevant section is shown.

Beautify

When vOrg mode is active, editing source code blocks in the vOrg file, the minor mode will auto set proper indentation, whitespace fixup and alignment of source code.

Additionally, manual beautification of source code blocks is made available with help of

C-c M-b   (vhdl-tools-vorg-src-block-beautify) - beautify code block at point

Tangling

Using references

Org mode includes special infrastructure to tangle org files containing source code. As explained in the org manual, extra comments may be inserted in the tangled code file. In particular, the “comments:link” option provides pointers back to the original org file, as a reference for jumping back and forth between vOrg and vhdl.

This behaviour is activated by setting the vhdl-tools-tangle-comments-link flag. Otherwise, only vhdl code is extracted from the vOrg file. The variables vhdl-tools-vorg-tangle-comment-format-beg and vhdl-tools-vorg-tangle-comment-format-end are used to format inserted comments in tangled code files.

Once the code is tangled from the vOrg file, the reference comments around in the source vhdl file are put out of sight with help of

vhdl-tools--cleanup-tangled

which is activated along with VDHL-tools.

Note that even if the vhdl-tools-tangle-comments-link flag is not set, the jumping features in vOrg minor mode may be used, except that in this case, a regular text search of text in current file is used to locate the point to jump to.

Conditional tangling

Conditionally tangling source code blocks is feasible too. This might be useful for code reuse between projects. This may achieved by setting the variable vhdl-tools-vorg-tangle-header-argument-var and setting a tag in the heading above the source code block. When no tags are given, the code block tangle header argument is set to current file name. If a tag is present, but different to the variable, the code block is ignored when tangling. This effectively acts as a filter, and provides a means to only tangle code blocks with tags in the variable vhdl-tools-vorg-tangle-header-argument-var, to be defined as a buffer or directory local variable.

As an example, setting a heading tag to “altera” will allow tangling source code blocks below only if the previous variable includes “altera”. When no tag is defined, all blocks are tangled.

*** Altera                                     :altera:

    #+begin_src vhdl-tools
      use work.cati_package.all;
    #+end_src

*** Juno mezzamine code                        :xilinx:

    #+begin_src vhdl-tools
      use work.juno_mezzanine_package.all;
      use UNISIM.VComponents.all;
    #+end_src

Heading inclusion

Heading inclusion in tangled code is implemented. This provides a way to replicate the file structure of the vOrg file in the source code file.

Tangling directory

Tangled code appears by default in the same directory where the vOrg file lies. However, it is possible to modify this behaviour. Using the variable vhdl-tools-vorg-src-vhdl-dir, source code may be extracted in a different directory to its vOrg sibling. When setting vhdl-tools-tangle-comments-link as explained in “Using references” section, it will be possible to jump back to the vOrg origin, effectively providing a means of splitting code appart. Along with “Conditional tangling”, this provides a way to develop code common to different targets, families, etc.

Publishing

Publishing is one of benefits of using org and the literate programming paradigm. It may achieved with help of

C-c M-P   (vhdl-tools-vorg-publish) - Publish project

Before publishing, one has to define the project configuration with help of, for example, a .dir-locals.el file containing something similar to

((nil
  (org-publish-project-alist . (("CatiROC-test-firmware"
                                 :base-directory "/home/User/MyProjects/src-vorg/"
                                 :publishing-directory "/tmp/src-html/"
                                 :publishing-function org-html-publish-to-html
                                 :makeindex nil
                                 :section-numbers nil
                                 :auto-sitemap t
                                 :sitemap-filename "index"
                                 :sitemap-title "CatiROC tests Firmware"
                                 :with-toc t )))))

An example project using this feature may be found here, where all local vOrg files has been published.

Add a custom footer
Add a custom sidebar
Clone this wiki locally