=============
Documentation
=============

.. Modified: 2019-10-20/19:15-0400 btiffin
.. Copyright 2016 Brian Tiffin
.. This file is part of the Unicon Programming document
.. GPL 3.0+ :ref:`license`

.. image:: images/unicon.png
   :align: center

.. only:: html

    :ref:`genindex`
    :floatright:`<a href="http://unicon.sourceforge.net/">Unicon</a>`

.. index:: documentation

.. _documentation:

Documenting Unicon programs
===========================

Unicon headers
--------------

:ref:`Ralph Griswold <Ralph>` 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 :ref:`IPL <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.

.. index:: skeleton.icn

.. literalinclude:: examples/ipl-skeleton.icn
   :language: unicon

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/ipl-skeleton.icn`

The empty section in the middle if meant for the program synopsis and
explanation.  All the programs in the :ref:`IPL <ipl>` follow this convention.

Personal
........
For most of the files in this doc set, a different template is used\
[#iplweb]_.

.. sourcecode:: unicon

    ##-
    # 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 :ref:`tectonics <tectonics>` for the definition of the word, meaning *from
source build instructions*, in this docset.

.. [#iplweb]

    That might be a mistake. These headers will not produce valid results
    from the :ref:`IPL <ipl>` indexing program, iplweb.icn.


.. index:: vim

vim autoload
............
With :ref:`Vim <vim>`, adding these skeletons to new Unicon files is as easy
as adding one line to a ``.vimrc`` file.

.. sourcecode:: vim

    " 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:

.. sourcecode:: vim

    " 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 :ref:`VimL <VimL>` function definition.

--------


.. index:: unidoc

.. _unidoc:

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 :ref:`package <package>`\d utilities that ship with Unicon.

--------


.. index:: utr

.. _utr:

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


.. only:: html

   ..

   --------

   :ref:`genindex` | Previous: :doc:`features` | Next: :doc:`testing`

   |