Part I: Eiffel-View 1.0, the new Eiffel repository publishing tool

Repository Publishing

If you have published your Eiffel code in a source repository like Github or Source Forge you will know that this is not the most ideal way to browse and explore Eiffel source code. There are a number of problems:

1. Browsing in github requires endless drilling down into a deep directory structure and there is a noticeable delay for pages to load. What is preferable is a less granular view of the directory structure that will eliminate a lot of drilling down.
2. If a class contains useful note documentation, you won't know about it's existence unless you actually open the class. Most times you will open the class and will discover there is no useful documentation. A wasted page load! What is need is a way to present any useful class notes on the same page as the link to the source code. If only some of the classes in a directory have useful notes, these should be listed first.
3. Class notes are viewable only in source code form. If they contain any useful formatting information, there is no possibility to see it rendered in HTML.
4. Once you open the source view, you will find that in github the indentation tabs are too large, so often the code does not fit nicely into the available browser space. Three spaces per tab is a much better default.
5. If you want to see an example of how a library class is used, be prepared to spend a lot of time looking for an example.
6. If you are only interested to read the code, the line number margin is a waste of space.

Introducing Eiffel-View

Eiffel-View is a new repository publishing tool that provides a solution to the code browsing problems identified in the introduction. However it does not manage the code, so you still need github or similar. It has been used to publish all the source code for the Eiffel-Loop repository which you can see here: www.eiffel-loop.com.

Part II to follow

This article is in two parts. In a follow up article I will be outlining some further improvements that could be made to make the tool more universally useful.

Features

Repository Statistics

A short summary of the repository contents is placed at the top of the home page. As for example:

Repository Statistics
1784 Eiffel classes containing 435288 words* of code. Total source code: 4.2 mb.
* Code words include keywords, identifier words and quoted strings, but exclude comments and indexing notes.

Dependency checking

A CRC-32 digest of each source code file is placed as a meta-tag of the corresponding html page. Eiffel-View is smart enough to work out the dependencies of every generated html page. Only pages that need rewriting are rewritten on subsequent runs.

Synchronization

Automatically synchronizes contents with the hosting site by ftp.

Note field markdown rendering

Eiffel-View renders as html markdown used in the class description field. The markdown used is similar to Github markdown but there are some differences.

All relative paths

All links to image files, style sheets etc, use relative paths. This means the website can be browsed locally in a directory folder.

Source Bookmarking Link

Each source code html page has a book mark link at the top. However it links to an anchor in the index page, not the source file itself.

Prism Syntax Highlighting

Eiffel-View makes use of the Prism js/css tool for syntax highlighting the Eiffel source code.

Client Example Links

Eiffel-View provides links to usage examples (maximum of 20) for any classes in the library folder. In Eiffel-Loop the usage examples are found in either the example, tool or test directories.For an example see class EL_MODULE_EVOLICITY_TEMPLATES

Configuration file

A configuration file allows you specify a list of named directories that will appear in the home page sitemap. This is a more granular approach then using ECF files to specify the repository contents.

doc-config/config.pyx

The file is written in Pyxis format. The ftp-site section is optional.[img_assist|nid=739|title=|desc=|link=node|align=left|width=736|height=990]

Eiffel-View Markdown Summary

Highlighted sections

Words quoted with a grave accent ` to open and an apostrophe ' to close are `highlighted'. This follows an established Eiffel convention used in source comments for quoting routine names. See class EL_REMOTE_ROUTINE_CALL_REQUEST_HANDLER for an example.

Bold words

This is the same as Github markdown. Use two asterisk on either side of the **words you** want to make bold

Code blocks

Consecutive lines in the description which have an indent of 3 or more tabs are highlighted as a quoted code block with a fixed size font. See class EIFFEL_FEATURE_EDITOR_APP for an example.

Hyper links

Hyper links use the same convention as mediawiki-formatting as for example:[http://website.com See here]

Relative source links

There is a specialized link that allows you reference other source code files in a class description. You write the link as though you were referencing the other Eiffel source file and then you change the .e extension to .html. For example:note description: "[ See class [../../eiffel-dev/class-edit/support/feature_constants.html FEATURE_CONSTANTS]. ]"See class EIFFEL_FEATURE_EDITOR_APP for an actual example.

Note that if you want to reference a class in the same directory you need to precede the page name with ./ as in this example for class EL_C_CALLABLE.

Tool Source Code

The source code for Eiffel-view can be viewed in directory tool/eiffel/source/library/publish.

Tool Download

A binary for the tool is available on Github as part of the 1.4.0 release of Eiffel-Loop:

el_toolkit-1.1.20

The build is for Linux Mint 17 which is based on Ubuntu 14.04. It might work on other versions of Ubuntu but I haven't tested.

Tool Usage

The following script found in the Eiffel-Loop root directory shows how to use the tool# File: build_doc.sh export EIFFEL_LOOP=$(pwd) export EIFFEL_LOOP_DOC=$EIFFEL_LOOP/doc read -p 'Enter a version number: ' version el_toolkit -publish_repository -config doc-config/config.pyx -version $version

HTML Templates

The following are links to github for the HTML page templates that comprise Eiffel-Loop.

• doc-config/main-template.html.evol
• doc-config/directory-tree-content.html.evol
• doc-config/eiffel-source-code.html.evol
• doc-config/site-map-content.html.evol

The text substitution language is Evolicity, which is a part of Eiffel-Loop.