WoC

From Idiki

This idea is under development. If you want to help its development ask in the discussion page, or if you prefer, contact the first submitter of the idea.

1 The idea
2 Implementation
- 2.1 Protocol
- 2.2 Client
3 See also

[edit]

The idea

WoC stands for Web Of Code.

The basic idea is to add hyperlink capacities to source code documents.

[edit]

Idea background

The idea was inspired by cscope. It is a tool used to browse source code. Before reading further this idea, try using Vim+Cscope. (Note: in this article, when talking about 'cscope', we are referring to a generic cscope program, not to the specific cscope. For example, there is a cscope for python [1]).

From the Vim user point of view, using cscope is like having internal links inside the source code. For example, you can "jump" on a keyword and Vim will open the source code where that keyword is defined.

A first primitive cscope hack is to add a fake #define in a specific place and then referring to it. For example, suppose you've written an API description in a comment inside a .h header file. Before the beginning of the comment you can put #define api_xyz_desc. In another file, when talking about that API, you'll add "..., for more info see api_xyz_desc". The reader will just have to use cscope to jump to api_xyz_desc, ending up at the beginning of the comment describing the API.

[edit]

Web Of Code

The natural evolution of this primitive hack is the addition of hyper-jumps, i.e. jump leading to source code placed in remote hosts. This is exactly what happens when clicking on an web URL referring to an external site. The 'hyperlinks' are the fundamental elements of the Web.

However, unlike the Web, which is used for general text documents, WoC is tuned appositely for source codes. Since it is based on cscope, its "jump to definition" command will be only one of its useful features, f.e. another one would be the "find reference to this symbol". The general WoC workflow is then:

The server B, creates a cscope database for each hosted source code

Client A sends to server B a cscope command, relative to a hosted source code, to the server B.

If the result of the command is unique, then the server sends to A the source file and the coordinates of the result, otherwise,
- Server B sends back the cscope output to A
- Client A parses the output and waits the user's choice
- Client A sends the new command to B, and the loop repeats

[edit]

Some details

Two new syntaxes has to be introduced: one used to define a generic tag and another to refer to a particular tag. For the former, any text placed inside (: and :) becomes a tag, while for the latter, any text placed inside : and : becomes a reference to a tag of the same name, i.e. a link. Using these syntaxes we can rewrite the above example of the #define hack as follow: at the start of the API description, inside the comment itself we put (:api_xyz_desc:), then to reference it we'll write ..., for more info see :api_xyz_desc:.

There should be also an option to change these syntaxes, because they may conflict with some programming languages.

The name of a source file should always be considered a tag defined at the start of the document, while filename:n should be considered a tag defined in the line n of the file filename. In this way, it is possible to jump to a particular line of a source file.

A reference to a remote tag would be in the following form: :hostname/package/TAG:. To avoid using long strings, it will be possible to use an aliases file, f.e. if we put

      gcc	gnu.org/cgi-bin/WoC.cgi/gcc/

inside the alias file of our source code, then writing :gcc/A_GCC_TAG: would be the same of :gnu.org/cgi-bin/WoC.cgi/gcc/A_GCC_TAG:.

In order to specify a cscope command inside a tag reference, it is possible to use this syntax: :TAG(cmd):
cmd is the abbreviation or the initials of a cscope command. Some cscope commands:

      c: Find functions calling this function
      d: Find functions called by this function
      e: Find this egrep pattern
      f: Find this file
      g: Find this definition
      i: Find files #including this file
      s: Find this C symbol
      t: Find assignments to

For example, consider this reference:

       :api_xyz_desc(g):

Jumping to this reference would be the same of issuing the "g: Find this definition" command for the tag "api_xyz_desc".

[edit]

Extending WoC

This is actually a sub-idea of WoC. In a python language it can be expressed as:

       from remote_url/WoC_url/code import Whatever

Assuming we're using the alias

       openssl		openssl.org/cgi-bin/WoC.cgi/ssl

an example would be something like:

       from :openssl/ssl: import RSA*

Let's go into the details.
Nowadays when you want to reuse the code written by someone else you have to brutally copy and incorporate it in your source code. The libraries mitigate this situation, but they are basically the same: you have to install the whole library even if you need a small part of it. From this, arise all the dependency problems, which the package managers, like the Gentoo portage, try to mitigate.

In the Web these "reusability" problems don't exist, in fact, a site that wants to refer to another site, simply use a link or a php 'include()' directive (or something else).

Using WoC's resources, it would be possible to import code hosted in remote places. The only difference would be that instead of '#including' local files, you'll include remote sources. A pre-pre code processor, would then download the included remote code, save it in a cache (to avoid to download the same thing multiple times) and fix it for compilation.

Using this technique, it won't be anymore necessary to depend on a whole library, moreover the way the dependencies are managed will change too, in fact, the only necessary steps would be to just compile and install the package.

A minor drawback would be that the same problems that afflict the Web will also interest this system. For example, changes of URLs, hostname and broken links.

[edit]