Part I: Eiffel-View 1.0, the new Eiffel repository publishing tool
- Repository Publishing
- Introducing Eiffel-View
- Part II to follow
- Configuration file
- Eiffel-View Markdown Summary
- Tool Source Code
- Tool Download
- Tool Usage
- HTML Templates
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:
- 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.
- 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.
- 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.
- 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.
- 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.
- If you are only interested to read the code, the line number margin is a waste of space.
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.
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.
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.
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
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.
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
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.
This is the same as Github markdown. Use two asterisk on either side of the **words you** want to make bold
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 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 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.
A binary for the tool is available on Github as part of the 1.4.0 release of Eiffel-Loop:
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.
The following script found in the Eiffel-Loop root directory shows how to use the tool
# File: build_doc.sh
read -p 'Enter a version number: ' version
el_toolkit -publish_repository -config doc-config/config.pyx -version $version
The following are links to github for the HTML page templates that comprise Eiffel-Loop.
The text substitution language is Evolicity, which is a part of Eiffel-Loop.
Is there any reason to have gray background? (The text looks next to unreadable to me in this setting.)
Also looking at random classes of Eiffel-loop libraries it turns out they do not provide much information how to use them, in particular because of missing class descriptions and empty feature comments.
Probably because I am old school. Back in the early days of the Internet in the 90's, the most popular web browser was called Netscape Navigator, and the default background color was, guess what.. gray.
I find that for long periods of reading that the high contrast of black on white hurts my eyes. I much prefer either gray (or pale green).
For the same reason I'm dimming my display so that everything appears in reasonably low contrast. This works almost in all cases except this one. Hopefully this affects only me.
One suggestion for you is to override the style sheet colors in your browser preferences with a background color of your own choosing. I don't think you can do this on Chrome but on Firefox it's
about:preferences#contentand in IE it's in the accessibility options.
Missing class descriptions
Publishing my source on a website is the first step of a long term project to provide better documentation. Now that they can be rendered as HTML I have a bigger incentive to supply descriptions for classes and in fact I have already spent time adding them. I also have separately written documentation for many modules that I plan to integrate later.
But if there are some classes you are particularly interested in, let me know and i will see what I can do