Documentation

Index Unicon

Documenting Unicon programs

Unicon headers

Ralph Griswold was fond of full intent documentation at the top of his Icon programs. Unicon can continue that tradition. Comment blocks at the top of a source file, with a little discipline to allow for machine readable processing, is a cheap and effective way to document small programs, and to help keep them organized. The IPL has a sample of the skeleton file that can be used to start a new Unicon source file. This author recommends taking a copy of that, customizing it to suit your preferences and use it for each and every program you write, large or small.

############################################################################
#
#	File:     
#
#	Subject:  Program
#
#	Author:   
#
#	Date:     
#
############################################################################
#
#  This file is in the public domain.
#
############################################################################
#
#
#
############################################################################
#
#  Requires:  
#
############################################################################
#
#  Links:
#
############################################################################

procedure main()

end

examples/ipl-skeleton.icn

The empty section in the middle if meant for the program synopsis and explanation. All the programs in the IPL follow this convention.

Personal

For most of the files in this doc set, a different template is used[1].

##-
# Author: Brian Tiffin
# Dedicated to the public domain
#
# Date: October 2016
# Modified: 2019-10-20/19:15-0400 btiffin
##+
#
# filename.icn, purpose
#
# tectonics
#
procedure main()

end

For the document generator, a special feature of docutils literal include is used, where each listing is included with the option:

:start-after: ##+

The listings in the book aren’t burdened with repetitive rights information, but when downloaded, the copyright and license (or dedication) is included so everyone clearly knows how the source can be used.

See tectonics for the definition of the word, meaning from source build instructions, in this docset.

[1]	That might be a mistake. These headers will not produce valid results from the IPL indexing program, iplweb.icn.

vim autoload

With Vim, adding these skeletons to new Unicon files is as easy as adding one line to a .vimrc file.

" Auto load Unicon template
autocmd BufNewFile  *.icn      0r ~/lang/icon/skeleton.icn

Now, every time you start an empty .icn file in vim it’ll be preloaded with your personal template. The 0r vim command (read at 0) is followed by a site-local filename; customize the ~/lang/icon/ part to match your setup.

If you don’t want the skeleton for a particular file, tapping u for undo, at the start of an edit, will clear the template.

Another sequence in Vim that is very handy, auto modification stamping:

" Auto update modified time stamp
"    Modified (with colon) must occur in the first 16 lines,
"    32 chars of data before Modified tag remembered
"    modify strftime to suit
function! LastModified()
    if &modified
        let save_cursor = getpos(".")
        let n = min([16, line("$")])
        keepjumps exe '1,' . n . 's#^\(.\{,32}Modified:\).*#\1'
            \ . strftime(" %Y-%m-%d/%H:%M%z") . '#e'
        call histdel('search', -1)
        call setpos('.', save_cursor)
    endif
endfunction
au BufWritePre * call LastModified()

Add that to ~/.vimrc.

Now, on file write, a top Modified: line will get a nice timestamp.

The routine only looks at the first 16 lines of text. The function also limits the scan for the Modified: tag within the first 32 characters of each line. You can customize all three of these preferences by changing the literals in the VimL function definition.

---

unidoc

There is an extensive API style documentation tool that ships with the Unicon source tree, unidoc, by Robert Parlett. Nice. From your source kit, see uni/unidoc/docs/html/index.html for a quick, yet detailed, view of some of the packaged utilities that ship with Unicon.

---

Unicon Technical Reports

There is an abundance of technical documentation for Unicon and Icon. Unicon programmers are fortunate that the core reference materials are in the Public Domain, or use liberal usage and redistribution licensing. User guides and deep implementation documentation are freely available. Extension and enhancement materials in the form of Technical Reports are also a click away, and can be redistributed with applications.

http://unicon.sourceforge.net/reports.html

---

Index | Previous: Features | Next: Testing