+)
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+You can obtain this info via InsetInfo (e.g.
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+info-insert buffer vcs-date
+\end_layout
+
+\end_inset
+
+).
+ The information will be available only when you have the file stored under
+ svn managment (i.e.
+ the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+.svn
+\end_layout
+
+\end_inset
+
+ directory is available with your document).
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Another---a hacking one---possibility is to use svn keywords
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html
+\end_layout
+
+\end_inset
+
+.
+ In short -- you set file keywords property (e.g.
+
+\family sans
+svn propset svn:keywords 'Rev' file.lyx
+\family default
+) and then paste keyword TeX code
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+This is an easy way how to ensure that LyX won't break the line in the middle
+ of keyword tag.
+\end_layout
+
+\end_inset
+
+ tag in your document (e.g.
+
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+$Rev$
+\end_layout
+
+\end_inset
+
+).
+ This way svn client will automatically substitute revision number (e.g.
+
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+$Rev: 59 $
+\end_layout
+
+\end_inset
+
+) after each update and commit.
+ There are more problems with this approach.
+ Firstly, the '$' character is used in TeX world for math equations, so
+ any occurence of math formula
+\begin_inset Formula $Rev$
+\end_inset
+
+ become
+\begin_inset Formula $Rev:59$
+\end_inset
+
+ in your LyX document.
+ Similarly for other keywords like Id, Date, Author, etc.
+ Secondly svn output is dependent on your locales, so its very easy that
+ svn would produce some problematic strings once Date is used.
+ Thirdly you get the whole 'Rev: 59' string in your document instead of
+ the plain number.
+ Until subversion implements user's custom keywords it will be hard to use
+ this approach reliably or let LyX to support it directly.
+\end_layout
+
+\begin_layout Subsection
+SVN and Windows Environment
+\end_layout
+
+\begin_layout Quote
+My inclination is to say that if the user cannot figure out the command
+ line operations on their own fairly quickly, they would be well advised
+ to use TortoiseSVN.
+ ---P.
+ A.
+ Rubin
+\end_layout
+
+\begin_layout Subsubsection
+Preparation
+\end_layout
+
+\begin_layout Standard
+In addition to installing LyX, and having access to a Subversion repository,
+ the user will need to install the Subversion client program.
+ A Windows installer for the client program is available from
+\begin_inset CommandInset href
+LatexCommand href
+name "CollabNet"
+target "http://www.collab.net/nonav/downloads/subversion/"
+
+\end_inset
+
+.
+ The user may also want to install
+\begin_inset CommandInset href
+LatexCommand href
+name "TortoiseSVN"
+target "http://tortoisesvn.tigris.org/"
+
+\end_inset
+
+, which integrates Subversion operations into the context (rightclick) menu
+ of Windows Explorer.
+ Operations done outside LyX will typically be more convenient using the
+ Explorer context menu.
+ Note that TortoiseSVN is not a replacement for the client program, which
+ is what LyX itself will use.
+\end_layout
+
+\begin_layout Subsubsection
+Bringing a document under Subversion control
+\end_layout
+
+\begin_layout Standard
+Before a LyX document can be brought under version control in Subversion,
+ its parent directory needs to be under version control.
+ If the document is being added to a project already in the repository,
+ this is accomplished by checking the project out to the directory where
+ the new document will be placed.
+ If the project itself is not yet under version control (for instance, if
+ this document starts a new project), the directory must be imported into
+ the repository.
+ This is done outside LyX.
+ Both import and checkout are easily accomplished from the Explorer context
+ menu using TortoiseSVN, or alternatively can be done using the command
+ line client at a DOS prompt.
+ The procedure for importing the project using TortoiseSVN is described
+ below, assuming an existing repository and a new project being started
+ in
+\family typewriter
+C:
+\backslash
+new project
+\family default
+.
+ For information on using the Subversion client program, run
+\family typewriter
+svn --help
+\family default
+in a DOS shell.
+\end_layout
+
+\begin_layout Enumerate
+Locate
+\family typewriter
+C:
+\backslash
+new project
+\family default
+in Windows Explorer, right click it, and select
+\family sans
+TortoiseSVN\SpecialChar \menuseparator
+Repo-browser
+\family default
+.
+ If necessary, adjust the URL for the repository, then click OK.
+\end_layout
+
+\begin_layout Enumerate
+Right click the level of the repository under which you want to place the
+ new project folder (typically the top level) and click
+\family sans
+Create folder
+\family default
+ Supply a name for the project folder and click OK.
+ Add a message for the log file if desired, then click OK again.
+ The new project folder should appear in the repository.
+ Finally, click OK again to exit the repository browser.
+\end_layout
+
+\begin_layout Enumerate
+Once again right click
+\family typewriter
+C:
+\backslash
+new project
+\family default
+, this time selecting SVN Checkout\SpecialChar \ldots{}
+ Select the URL of the project folder
+ you just created in the repository, and set the checkout directory to
+\family typewriter
+C:
+\backslash
+new project.
+
+\family default
+ Click OK.
+ You will be warned about a non-empty folder; click OK to proceed.
+ You should now have a
+\family typewriter
+.svn
+\family default
+ directory under
+\family typewriter
+C:
+\backslash
+new project.
+\end_layout
+
+\begin_layout Enumerate
+Create or open your document in LyX and click
+\family sans
+File\SpecialChar \menuseparator
+Version
+\begin_inset space ~
+\end_inset
+
+Control\SpecialChar \menuseparator
+Register.
+
+\family default
+Add a log message and click OK to commit the document to version control.
+\end_layout
+
+\begin_layout Standard
+From this point onward, you should have full functionality in the
+\family sans
+File\SpecialChar \menuseparator
+Version
+\begin_inset space ~
+\end_inset
+
+Control
+\family default
+ menu.
+ You also have the option of checking the document in and out, viewing its
+ history, etc.
+ using the TortoiseSVN context menu in Windows Explorer or the Subversion
+ client program from a command prompt.
+\end_layout
+
+\begin_layout Subsubsection
+SSH tunnel used with SVN under Windows
+\end_layout
+
+\begin_layout Standard
+Compared with Linux setting up an svn client to communicate over ssh under
+ Windows is a rather troublesome task.
+ We will at least offer some hints how to setup the client side but prior
+ knowledge about ssh and the Windows command line is needed, also be prepared
+ for a great deal of frustration\SpecialChar \ldots{}
+
+\end_layout
+
+\begin_layout Enumerate
+Get an svn client for windows, as described in the previous sections.
+ When it is a fresh install run some svn command (e.g.
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+svn --version
+\end_layout
+
+\end_inset
+
+) to create config files, which you will need to change later on.
+\end_layout
+
+\begin_layout Enumerate
+Choose an ssh client for Windows.
+ There are several possibilities, we will use the one from Putty tools
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+.
+ You will need to set the connection up so that the client doesn't ask for
+ any password from you.
+ To keep things easy we will use only keys without any additional password
+ protection etc.
+\end_layout
+
+\begin_deeper
+\begin_layout Enumerate
+Generate keys by
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+puttygen
+\end_layout
+
+\end_inset
+
+.
+ Save your private .ppk key file and put the public one on the server side.
+ If the SVN server runs on Linux, note that the format of the public key
+ is not compatible with Linux openssh and you will need to direcly copy-paste
+ the key from the “
+\emph on
+Public key for pasting into OpenSSH authorized_keys file
+\emph default
+:” edit field into the server's
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+~/.ssh/authorized_keys
+\end_layout
+
+\end_inset
+
+ /
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+authorized_keys2
+\end_layout
+
+\end_inset
+
+ file.
+\end_layout
+
+\begin_layout Enumerate
+Get the Putty's
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+plink
+\end_layout
+
+\end_inset
+
+.
+ In the SVN config file
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+Exact path depends on Windows version, usually somewhere around
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+c:
+\backslash
+Documents and Settings
+\backslash
+user
+\backslash
+Application Data
+\backslash
+Subversion
+\backslash
+config
+\end_layout
+
+\end_inset
+
+ /
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+AppData
+\backslash
+Roaming
+\backslash
+Subversion
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\end_inset
+
+, section [tunnels], setup ssh command, e.g.
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ssh=c:/path/plink.exe -i c:/path/private_key.ppk
+\end_layout
+
+\end_inset
+
+.
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+It will usually take a lot of time to get exact command right and it depends
+ on many things.
+ For example do not have some remote server saved as a default session in
+ Putty etc.
+ If things fail, try to connect via plink without SVN first.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Checkout the SVN archive, e.
+\begin_inset space \thinspace{}
+\end_inset
+
+g.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+svn co svn+ssh://user@server/repository_path
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsubsection
+End-of-Line Conversions
+\end_layout
+
+\begin_layout Standard
+When the collaborators are mixing Linux and Windows environments, LyX will
+ use different line endings inside the .lyx files.
+ This is not a problem as far as LyX functionality is concerned, but the
+ commit diffs will be huge and merge-conflicts prone.
+ Fortunately SVN itself knows
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+http://svnbook.red-bean.com/en/1.4/svn.advanced.props.file-portability.html
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+ how to deal with CR/LF problems when switching .lyx files to the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+native
+\end_layout
+
+\end_inset
+
+ mode.
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+For the lazy guys:
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+svn propset svn:eol-style native FILE_NAME
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+GIT commands in LyX
+\end_layout
+
+\begin_layout Standard
+A minimal subset of GIT commands is now supported by LyX.
+ You can find the commands in the
+\family sans
+File\SpecialChar \menuseparator
+Version
+\begin_inset space ~
+\end_inset
+
+Control
+\family default
+ submenu.
+ Please note that if you use password protected access to repository via
+ ssh, you will be asked in terminal window.
+ LyX was tested against GIT 1.7.
+\end_layout
+
+\begin_layout Standard
+One big difference of GIT and the other supported version control systems
+ is the distributed nature of GIT: With traditional version control systems
+ there is one central server which hosts the repository.
+ Users commit their changes to the server, and get updates made by other
+ users from it.
+ With GIT, users commit to a local repository.
+ The local repository can be synchronized with one or more remote repositories
+ using the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+pull
+\end_layout
+
+\end_inset
+
+ and
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+push
+\end_layout
+
+\end_inset
+
+ GIT commands.
+ LyX does not interact in any way with remote GIT repositories.
+ It works exclusively with the local repository in a very similar way as
+ with a central CVS or SVN repository.
+ If you use remote GIT repositories you need to do the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+pull
+\end_layout
+
+\end_inset
+
+ and
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+push
+\end_layout
+
+\end_inset
+
+ operations with your favourite GIT client.
+\end_layout
+
+\begin_layout Subsubsection
+
+\family sans
+Register
+\end_layout
+
+\begin_layout Standard
+If your document is not under revision control, this is the only item shown
+ in the menu.
+ And if it is under revision control, the
+\family sans
+\bar under
+R
+\bar default
+egister
+\family default
+ item is not visible.
+\end_layout
+
+\begin_layout Standard
+This command registers in GIT your document ONLY in case you have already
+ the documents directory under GIT control (in particular
+\family typewriter
+.git/index
+\family default
+ file exists).
+ This means you have to checkout the archive by yourself.
+\end_layout
+
+\begin_layout Standard
+Then you are asked interactively to supply an initial description of the
+ document.
+ Don't forget that registered file is not yet commited.
+\end_layout
+
+\begin_layout Standard
+GIT command that is run:
+\family typewriter
+git add
+\begin_inset Quotes eld
+\end_inset
+
+<file-name>
+\begin_inset Quotes erd
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Read
+\family typewriter
+man git
+\family default
+ to understand the switches.
+\end_layout
+
+\begin_layout Subsubsection
+
+\family sans
+Check In Changes
+\end_layout
+
+\begin_layout Standard
+When you are finished editing a file, you commit your changes.
+ When you do this, you are asked for a description of the changes.
+ After that changes are commited.
+\end_layout
+
+\begin_layout Standard
+GIT command:
+\family typewriter
+git commit -q -m"<description>" <file-name>
+\end_layout
+
+\begin_layout Subsubsection
+
+\family sans
+Revert To Repository Version
+\end_layout
+
+\begin_layout Standard
+This will discard all changes made to the document since the last check
+ in.
+ You get a warning before changes are discarded.
+\end_layout
+
+\begin_layout Standard
+GIT command:
+\family typewriter
+git checkout -q
+\begin_inset Quotes eld
+\end_inset
+
+<file-name>
+\begin_inset Quotes erd
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+
+\family sans
+Rename
+\end_layout
+
+\begin_layout Standard
+This will rename the current document including the version history.
+ It requires a clean document without any changes since the last checkin.
+ You are asked for a file name and a description of the rename operation.
+ After that the document is renamed, both locally and in the repository.
+ If the parent directories of the new and old file names differ, all relative
+ paths of included files are adjusted (like in
+\family sans
+File\SpecialChar \menuseparator
+Save As
+\family default
+\SpecialChar \ldots{}
+).
+ Finally, the document is reloaded using the new name.
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+GIT
+\begin_inset space ~
+\end_inset
+
+commands:
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+git mv
+\family typewriter
+
+\begin_inset Quotes eld
+\end_inset
+
+<file-name>
+\begin_inset Quotes erd
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+<new-file-name>
+\begin_inset Quotes erd
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+git commit
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+
+\family sans
+Show History
+\end_layout
+
+\begin_layout Standard
+This shows the complete history of the GIT document.
+ The output of
+\family typewriter
+git log
+\begin_inset Quotes eld
+\end_inset
+
+<file-name>
+\begin_inset Quotes erd
+\end_inset
+
+
+\family default
+ is shown in a browser.
+\end_layout
+
+\begin_layout Subsubsection
+Version Info
+\end_layout
+
+\begin_layout Standard
+LyX supports GIT hash number of the last commit to the file, author name,
+ date and time of last commit.
+ All those are extracted from
+\family typewriter
+git log -n 1 --pretty=format:%H%n%an%n%ai
+\family default
+.
+ Tree version information is obtained via
+\family typewriter
+git describe --abbrev --dirty --long
+\family default
+.
+ See
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:VCS-Revision-Information"
+
+\end_inset
+
+ for other details.
+\end_layout
+
+\begin_layout Subsection
+Further tuning
+\end_layout
+
+\begin_layout Standard
+With the recent addition of the vc-command function LyX power users are
+ allowed to create their own commands for revision control.
+\end_layout
+
+\begin_layout Standard
+As an example you can see how two TortoiseSVN commands could be integrated
+ directly:
+\end_layout
+
+\begin_layout Description
+Commit:
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+vc-command DR "." "TortoiseProc /command:commit /path:$$p"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Description
+Revert:
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+vc-command DR "." "TortoiseProc /command:revert /path:$$p"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Version control and Document comparison
+\end_layout
+
+\begin_layout Standard
+One of the typical uses of version control is to inspect the changes between
+ revisions, usually by creating
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+diff
+\end_layout
+
+\end_inset
+
+ dumps.
+ While this is useful for plain text files, it is much less useful in the
+ case of LyX files, which have more a complicated structure.
+ Hence we provide binding to the Document comparison feature.
+ There are two ways of calling this feature - either by direct call of
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+VC_COMPARE
+\end_layout
+
+\end_inset
+
+ LyX function (for details see LyX functions manual) or by icon/menu item
+
+\begin_inset Flex MenuItem
+status collapsed
+
+\begin_layout Plain Layout
+Compare with older revision...
+\end_layout
+
+\end_inset
+
+.
+ One can either compare two chosen revisions of the document or he can simply
+ compare the current version of edited text with older revisions (where
+ '
+\begin_inset Flex MenuItem
+status collapsed
+
+\begin_layout Plain Layout
+0
+\end_layout
+
+\end_inset
+
+' revisions back means comparison of the edited file with last commited
+ revision).
+
+\end_layout
+
+\begin_layout Standard
+This feature is supported for SVN and RCS though due to the more complicated
+ versioning scheme of RCS there is a constraint -- when addressing the revisions
+ in dialog, numbers always point to the last number in RCS revision number,
+ i.e.
+ '35' in '1.2.35'.
+ We don't currently support GIT addressing of revisions, one can just compare
+ edited document with its revision X steps backs, where X is addressed as
+ HEAD~X.
+\end_layout
+
+\begin_layout Section
+Literate Programming
+\end_layout
+
+\begin_layout Standard
+Updated by
+\noun on
+Kayvan Sylvan
+\noun default
+(kayvan@sylvan.com)
+\noun on
+,
+\noun default
+original documentation written by
+\noun on
+Edmar Wienskoski Jr.
+
+\noun default
+ (edmar-w-jr@technologist.com)
+\end_layout
+
+\begin_layout Subsection
+Introduction
+\end_layout
+
+\begin_layout Standard
+The main purpose of this documentation is to show you how to use LyX for
+ literate programming, where it is assumed that you are familiar with this
+ programming technique, and know what
+\begin_inset Quotes eld
+\end_inset
+
+tangling
+\begin_inset Quotes erd
+\end_inset
+
+ and
+\begin_inset Quotes eld
+\end_inset
+
+weaving
+\begin_inset Quotes erd
+\end_inset
+
+ means.
+ If that is not the case, please follow the web links provided in the following
+ sections.
+ There is a lot of good documentation out there covering old development
+ history to the latest tools tips.
+\end_layout
+
+\begin_layout Standard
+It is also assumed that you are familiar with LyX itself to a point that
+ you are comfortable changing your LyX preferences, and X resources file.
+ If that is not the case please refer to other LyX documentation to cover
+ your specific needs.
+\end_layout
+
+\begin_layout Subsection
+Literate Programming
+\end_layout
+
+\begin_layout Standard
+From the Literate Programming FAQ:
+\end_layout
+
+\begin_layout Quotation
+Literate programming is the combination of documentation and source together
+ in a fashion suited for reading by human beings.
+ In fact, literate programs should be enjoyable reading, even inviting!
+ (Sorry Bob, I couldn't resist!) In general, literate programs combine source
+ and documentation in a single file.
+ Literate programming tools then parse the file to produce either readable
+ documentation or compilable source.
+ The WEB style of literate programming was created by D.
+\begin_inset space \thinspace{}
+\end_inset
+
+E.
+ Knuth during the development of his TeX typesetting software.
+
+\end_layout
+
+\begin_layout Standard
+Another excerpt says:
+\end_layout
+
+\begin_layout Quotation
+
+\emph on
+How is literate programming different from verbose commenting?
+\end_layout
+
+\begin_layout Quotation
+There are three distinguishing characteristics.
+ In order of importance, they are:
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+flexible order of elaboration
+\end_layout
+
+\begin_layout Itemize
+automatic support for browsing
+\end_layout
+
+\begin_layout Itemize
+typeset documentation, especially diagrams and mathematics
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+Now that I sparked your curiosity, take a look in the references.
+\end_layout
+
+\begin_layout Subsubsection
+References
+\end_layout
+
+\begin_layout Standard
+The complete Literate Programming FAQ can be found at:
+\end_layout
+
+\begin_layout Quote
+Literate Programming FAQ
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+http://www.literateprogramming.com/lpfaq.pdf
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The FAQ lists 23 (twenty three!) different literate programming tools.
+ Where some are specialized or
+\begin_inset Quotes eld
+\end_inset
+
+tailored
+\begin_inset Quotes erd
+\end_inset
+
+ for particular programming languages, while other have general scope.
+ I selected
+\noun on
+Noweb
+\noun default
+ for my own use for several reasons:
+\end_layout
+
+\begin_layout Itemize
+It can generate the documentation either in LaTeX or HTML.
+\end_layout
+
+\begin_layout Itemize
+It has a open architecture, i.
+\begin_inset space \thinspace{}
+\end_inset
+
+e.
+\begin_inset space \space{}
+\end_inset
+
+it is easy to plug in new filters and to perform special processing that
+ you may need.
+
+\end_layout
+
+\begin_layout Itemize
+There is a good selection of filters available already (the HTML is one
+ of them).
+\end_layout
+
+\begin_layout Itemize
+It is free.
+\end_layout
+
+\begin_layout Standard
+The Noweb web page can be found at:
+\end_layout
+
+\begin_layout Quote
+Noweb home page
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+http://www.cs.virginia.edu/~nr/noweb/
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Starting from there you can reach many other interesting links and even
+ some literate program examples.
+\end_layout
+
+\begin_layout Subsection
+LyX and Literate Programming with Noweb
+\end_layout
+
+\begin_layout Standard
+The LyX support for Literate Programming is provided by using the generic
+ LyX converters mechanism.
+ This support is provided in a
+\begin_inset Quotes eld
+\end_inset
+
+Noweb independent
+\begin_inset Quotes erd
+\end_inset
+
+ way, i.
+\begin_inset space \thinspace{}
+\end_inset
+
+e.
+\begin_inset space \space{}
+\end_inset
+
+you will be able to use this new LyX feature with some other literate programmin
+g tool of your choice by just changing your LyX preferences.
+\end_layout
+
+\begin_layout Subsubsection
+Generating documents and code (weaving and tangling)
+\end_layout
+
+\begin_layout Paragraph
+Using the noweb module
+\end_layout
+
+\begin_layout Standard
+If you have installed Noweb and LyX successfully, whenever you open a new
+ document, after you have chosen its document class, use the Document->Settings
+ menu to add the
+\begin_inset Quotes eld
+\end_inset
+
+noweb
+\begin_inset Quotes erd
+\end_inset
+
+ module.
+ If Noweb is correctly installed, when you click on the
+\begin_inset Quotes eld
+\end_inset
+
+Modules
+\begin_inset Quotes erd
+\end_inset
+
+ link, you will see the
+\begin_inset Quotes eld
+\end_inset
+
+noweb
+\begin_inset Quotes erd
+\end_inset
+
+ module in the available list and you can add it to your document.
+\end_layout
+
+\begin_layout Paragraph
+Typing code in
+\end_layout
+
+\begin_layout Standard
+LyX enables you to write code with a layout named
+\begin_inset Flex Noun
+status collapsed
+
+\begin_layout Plain Layout
+Chunk
+\end_layout
+
+\end_inset
+
+.
+ Noweb delimits chunks like this:
+\end_layout
+
+\begin_layout LyX-Code
+<<My code>>=
+\end_layout
+
+\begin_layout LyX-Code
+ code
+\end_layout
+
+\begin_layout LyX-Code
+ more code
+\end_layout
+
+\begin_layout LyX-Code
+ even more code
+\end_layout
+
+\begin_layout LyX-Code
+ @
+\end_layout
+
+\begin_layout Standard
+The problem is that whatever is written in between the << and the
+\family typewriter
+@
+\family default
+ must be taken literally, i.
+\begin_inset space \thinspace{}
+\end_inset
+
+e.
+\begin_inset space \space{}
+\end_inset
+
+LyX should be prevented from making any special interpretation of what has
+ been written.
+ This is also handled by
+\begin_inset Flex Noun
+status collapsed
+
+\begin_layout Plain Layout
+Chunk
+\end_layout
+
+\end_inset
+
+, that works like a normal paragraph but has a free spacing capability.
+\end_layout
+
+\begin_layout Standard
+As a special note, you can also use the
+\begin_inset Quotes eld
+\end_inset
+
+%def
+\begin_inset Quotes erd
+\end_inset
+
+ construct of Noweb in your chunks to add items to Noweb's identifier cross-refe
+rence:
+\end_layout
+
+\begin_layout LyX-Code
+<<My chunk>>=
+\end_layout
+
+\begin_layout LyX-Code
+def some_function(args):
+\end_layout
+
+\begin_layout LyX-Code
+ "This is the doc string for this function."
+\end_layout
+
+\begin_layout LyX-Code
+ print "My args: ", args
+\end_layout
+
+\begin_layout LyX-Code
+@ %def some_function
+\end_layout
+
+\begin_layout Standard
+For an example of this usage and the resulting cross-reference output, look
+ at the Literate python program in
+\emph on
+LIBDIR/examples/listerrors.lyx
+\emph default
+ which should make this all clear.
+\end_layout
+
+\begin_layout Paragraph
+Generating the documentation
+\end_layout
+
+\begin_layout Standard
+At this point you already have a new document file with a proper document
+ class, and with some code and text on it.
+ How do I print it? The answer is simple, you select
+\family sans
+View\SpecialChar \menuseparator
+DVI,
+\family default
+ etc.
+ Just like you would do for a plain document.
+ No special procedure is required.
+\end_layout
+
+\begin_layout Standard
+To help orientate you, I will now explain what happens inside LyX:
+\end_layout
+
+\begin_layout Enumerate
+When the
+\family sans
+Update\SpecialChar \menuseparator
+DVI
+\family default
+ menu option is chosen, a LaTeX file is generated.
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+If the document is of any literate class the generated file will be named
+ with an extension name defined by the
+\begin_inset Quotes eld
+\end_inset
+
+literate
+\begin_inset Quotes erd
+\end_inset
+
+ format (defined in the Preferences panel), otherwise the file will have
+ the usual
+\family typewriter
+.tex
+\family default
+ extension.
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Note that the only difference so far is in the name of the file, no special
+ processing is required by LyX.
+ Given that you formatted the code using the
+\begin_inset Flex Noun
+status collapsed
+
+\begin_layout Plain Layout
+Chunk
+\end_layout
+
+\end_inset
+
+ layout that, by itself, takes care of the business.
+\end_layout
+
+\begin_layout Enumerate
+If the document is of any literate class LyX will then use the internal
+ LyX to Noweb converter, followed by the Noweb to LaTeX converter
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+The converters are defined in the
+\family sans
+Tools\SpecialChar \menuseparator
+Preferences
+\family default
+ panel, under the
+\begin_inset Quotes eld
+\end_inset
+
+Conversion
+\begin_inset Quotes erd
+\end_inset
+
+ tab.
+ See section
+\emph on
+Converters
+\emph default
+ of the
+\emph on
+Customization
+\emph default
+ manual for general information about converters.
+\end_layout
+
+\end_inset
+
+ to generate the LaTeX file.
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Otherwise it will just skip this step.
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Finally, LaTeX is invoked and the regular post processing continues as in
+ a plain document.
+\end_layout
+
+\begin_layout Standard
+Independence from a particular
+\begin_inset Quotes eld
+\end_inset
+
+literate tool
+\begin_inset Quotes erd
+\end_inset
+
+ is easily achieved by changing the commands that are run by the various
+ converters.
+\end_layout
+
+\begin_layout Paragraph
+Generating the code
+\end_layout
+
+\begin_layout Standard
+When the build menu option is chosen or the corresponding button in the
+ toolbar is pressed, a LaTeX file is generated just like step 1 above.
+ Next, LyX invokes the
+\family typewriter
+Noweb->Program
+\family default
+ converter.
+ This converter needs to be defined by the user and is not installed by
+ default, though the Program format is.
+ This converter (like any other converter) will have two parts:
+\end_layout
+
+\begin_layout Enumerate
+The converter program itself.
+ This program performs the conversion from the one format to the other (in
+ this case, from the Noweb format to the Program pseudo-format).
+\end_layout
+
+\begin_layout Enumerate
+The error log parser.
+ This is a program whose sole purpose is to rewrite error messages in a
+ format that LyX understands.
+ This makes it possible for LyX to place error boxes in the right places
+ in the file buffer.
+\end_layout
+
+\begin_layout Standard
+The first part, the
+\begin_inset Quotes eld
+\end_inset
+
+Converter
+\begin_inset Quotes erd
+\end_inset
+
+ setting, should be set to
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+build-script $$i
+\family default
+ $$r
+\begin_inset Quotes erd
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+This basically means that LyX will call
+\begin_inset Quotes eld
+\end_inset
+
+build-script
+\begin_inset Quotes erd
+\end_inset
+
+ (a program or script) with the name of the Noweb file (normally a file
+ in the LyX temp directory) and the directory path of the original LyX file.
+
+\end_layout
+
+\begin_layout Standard
+This is an implementation of
+\begin_inset Quotes eld
+\end_inset
+
+build-script
+\begin_inset Quotes erd
+\end_inset
+
+ that you can place in a directory on your path:
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace defskip
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Newpage pagebreak
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+
+\family sans
+#!/bin/sh
+\end_layout
+
+\begin_layout Standard
+
+\family sans
+#
+\end_layout
+
+\begin_layout Standard
+
+\family sans
+notangle -Rbuild-script $1 | env NOWEB_SOURCE=$1 NOWEB_OUTPUT_DIR=$2 sh
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace defskip
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The next part of the converter setting is the
+\begin_inset Quotes eld
+\end_inset
+
+Flags
+\begin_inset Quotes erd
+\end_inset
+
+ which is to be set to
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+parselog=$$s/scripts/listerrors
+\family default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+This will run any errors that are generated by the
+\begin_inset Quotes eld
+\end_inset
+
+build-script
+\begin_inset Quotes erd
+\end_inset
+
+ process through the
+\begin_inset Quotes eld
+\end_inset
+
+listerrors
+\begin_inset Quotes erd
+\end_inset
+
+ program.
+\end_layout
+
+\begin_layout Standard
+The build will normally take place in LyX's temporary directory, so the
+ files produced by the conversion will be in that directory.
+ LyX will copy out what it regards as the `main' file, but the
+\family typewriter
+Noweb->Program
+\family default
+ conversion may produce several files, and so most of these would then be
+ deleted when LyX was closed.
+ This is why we pass in the NOWEB_OUTPUT_DIR environment variable so that
+ the build-script chunk can place the generated files in that location.
+\end_layout
+
+\begin_layout Paragraph
+Build instructions in the document
+\end_layout
+
+\begin_layout Standard
+The last piece of the integration between LyX and noweb is the
+\begin_inset Quotes eld
+\end_inset
+
+build-script
+\begin_inset Quotes erd
+\end_inset
+
+ chunk.
+ Generally, the instructions for building your program should be embedded
+ in a chunk of its own.
+ The noweb-specific
+\begin_inset Quotes eld
+\end_inset
+
+build-script
+\begin_inset Quotes erd
+\end_inset
+
+ above uses the notangle command to look for this chunk (called
+\begin_inset Quotes eld
+\end_inset
+
+build-script
+\begin_inset Quotes erd
+\end_inset
+
+) and runs its contents through
+\begin_inset Quotes eld
+\end_inset
+
+sh
+\begin_inset Quotes erd
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+Typically, such a chunk would look something like this:
+\end_layout
+
+\begin_layout LyX-Code
+<<build-script>>=
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh
+\begin_inset Newline newline
+\end_inset
+
+if [ -z "${NOWEB_SOURCE}" ]
+\begin_inset Newline newline
+\end_inset
+
+then
+\end_layout
+
+\begin_layout LyX-Code
+NOWEB_SOURCE=myfile.nw
+\begin_inset Newline newline
+\end_inset
+
+fi
+\begin_inset Newline newline
+\end_inset
+
+[...
+ code to extract files ...
+ use NOWEB_OUTPUT_DIR here ...]
+\begin_inset Newline newline
+\end_inset
+
+[...
+ code to compile files ...]
+\begin_inset Newline newline
+\end_inset
+
+@
+\end_layout
+
+\begin_layout Standard
+Look in
+\emph on
+LIBDIR/examples/listerrors.lyx
+\emph default
+ or in
+\emph on
+LIBDIR/examples/Literate.lyx
+\emph default
+ which implement two versions of the
+\begin_inset Quotes eld
+\end_inset
+
+listerrors
+\begin_inset Quotes erd
+\end_inset
+
+ program for some illustrations of how all of these pieces go together or
+ in
+\emph on
+LIBDIR/examples/noweb2lyx.lyx.
+
+\emph default
+ Interestingly, these three files show off the language-indepence of the
+ LyX literate programming support since they are written in Python, C and
+ Perl respectively.
+\end_layout
+
+\begin_layout Subsubsection
+Configuring LyX
+\end_layout
+
+\begin_layout Standard
+All the Literate Programming support is configured by the
+\family sans
+Tools\SpecialChar \menuseparator
+Preferences
+\family default
+ panel in the
+\begin_inset Quotes eld
+\end_inset
+
+File Handling
+\begin_inset Quotes erd
+\end_inset
+
+ tab.
+ The important parts are:
+\end_layout
+
+\begin_layout Description
+the
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+NoWeb
+\begin_inset Quotes erd
+\end_inset
+
+
+\begin_inset space ~
+\end_inset
+
+format Set up via the File Formats tab, this is where the Noweb-specific
+ pieces are set up.
+ The
+\family sans
+GUI Name
+\family default
+ is set to
+\family typewriter
+NoWeb
+\family default
+, the file extension is set to
+\family typewriter
+.nw
+\family default
+.
+ This tells LyX to create a file with a
+\family typewriter
+.nw
+\family default
+ extension in the first step of the conversion process.
+\end_layout
+
+\begin_layout Description
+the
+\begin_inset space ~
+\end_inset
+
+
+\family sans
+Program
+\family default
+
+\begin_inset space ~
+\end_inset
+
+format This is an empty format whose sole purpose is to be the endpoint
+ of a conversion (which then allows us to set up a converter for it).
+\end_layout
+
+\begin_layout Description
+
+\family sans
+NoWeb
+\family default
+->
+\family sans
+LaTeX
+\family default
+ This converter performs the
+\begin_inset Quotes eld
+\end_inset
+
+weaving
+\begin_inset Quotes erd
+\end_inset
+
+ of the literate document.
+ For Noweb, it is set to
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+noweave -delay -index $$i > $$o
+\family default
+
+\begin_inset Quotes erd
+\end_inset
+
+
+\end_layout
+
+\begin_layout Description
+
+\family sans
+NoWeb
+\family default
+->
+\family sans
+Program
+\family default
+ This performs the
+\begin_inset Quotes eld
+\end_inset
+
+tangling step
+\begin_inset Quotes erd
+\end_inset
+
+.
+ As stated above, the Converter is set to
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+build-script $$i
+\family default
+ $$r
+\begin_inset Quotes erd
+\end_inset
+
+, with Flags set to
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+parselog=$$s/scripts/listerrors
+\family default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsubsection
+Debug extensions
+\end_layout
+
+\begin_layout Standard
+There is also a new function implemented in the LyX server, the
+\begin_inset Quotes eld
+\end_inset
+
+server-goto-file-row" function, to be used with ddd/gdb or other debugger.
+
+\end_layout
+
+\begin_layout Standard
+When debugging code with ddd/gdb, it is possible to invoke a text editor
+ at the current execution position with a single key stroke.
+ The default ddd configuration for that is shift-ctrl-V.
+ It happens that you can define the editor command line invocation in ddd
+ by accessing the
+\family sans
+Edit\SpecialChar \menuseparator
+Preferences\SpecialChar \menuseparator
+Helpers
+\family default
+ dialog and changing the "Edit Sources" entry.
+\end_layout
+
+\begin_layout Standard
+I take advantage of the newly created LyX server function and this ddd feature,
+ and set
+\begin_inset Quotes eld
+\end_inset
+
+Edit Sources
+\begin_inset Quotes erd
+\end_inset
+
+ to:
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace defskip
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+
+\family sans
+echo "LYXCMD:monitor:server-goto-file-row:@FILE@ @LINE@" >~/.lyxpipe.in
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace defskip
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+With this, whenever you are using ddd and find a point in the program that
+ you want to edit, you just press shift-ctrl-V (in the ddd window), and
+ ddd will forward this information to LyX through the LyX server and then
+ the LyX window will show the same file with the cursor at the same position
+ ddd was pointing to.
+ No more guessing or long scrolling to locate a point in the program back
+ from debugging !
+\end_layout
+
+\begin_layout Standard
+Note however that you must enable the LyX server to get this feature working
+ (it is disabled by default).
+ You can enable it in
+\family sans
+Preferences
+\family default
+ (tabs
+\family sans
+Inputs
+\family default
+,
+\family sans
+Paths
+\family default
+) by entering in the
+\family sans
+LyXserver pipe
+\family default
+ a path like
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+/home/<your-home-directory>/.lyx/lyxpipe
+\family default
+
+\begin_inset Quotes erd
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Read the LyX server documentation in the
+\emph on
+Customization Manual
+\emph default
+ for further information.
+\end_layout
+
+\begin_layout Subsubsection
+Toolbar extensions
+\end_layout
+
+\begin_layout Standard
+There are six new buttons that can be added to your LyX toolbar.
+ Five of these buttons are short cuts to layout styles:
+\family sans
+Standard
+\family default
+,
+\family sans
+Section
+\family default
+,
+\family sans
+LaTeX
+\family default
+,
+\family sans
+LyX-Code
+\family default
+, and
+\family sans
+Chunk
+\family default
+.
+ The last one is a short cut to the
+\begin_inset Quotes eld
+\end_inset
+
+Build Program
+\begin_inset Quotes erd