Clean up the documentation

[Alpar Juttner]

This task should be done after the 1.0 release branch will have been created.

Documentation contains references to tools that has not yet been ported from the svn. (For example there are empty modules is the doc.) These parts must be removed before the release.

[Peter Kovacs]

There are some tasks that should be done before creating the branch for 1.0, too. I think the followings are important.

1. Related pages, that would be nice to port:
   • Named Parameters (there are a lot of reference for that, e.g. in bfs.h, dfs.h, dijkstra.h)
   • How to start using LEMON, Getting Started (they should be revised and maybe merged)
   • Quick Tour to LEMON (it contains some features that won't be part of the 1.0 release, e.g. LP, so maybe it would be better to postpone the port of this page)

2. The modules page should be revised.
   • The name of the groups are inconsistent (e.g. "Path structures", "Graph structures", but "Maps"; using capitals in titles is not consequent; etc.).
   • I would prefer a new arrangement in which a module contains either submodules or elements (i.e. classes, functions etc.), but not both. E.g. In Maps module there are two sections: "Graph Maps", "Map Adaptors", so reading the modules page a user may think that all of the maps are either graph map or map adaptor. I suggest an other section called "Other Maps" or something similar. It would cause a more logical and clear list of modules that can be used like a "table of contents" for LEMON.
   • In a separate branch the empty modules should be removed.

3. Since we don't have tutorial yet, a few demo programs would be important in the 1.0 release. Now we have three demos, but I suggest to add hello_lemon.cc, dijkstra_demo.cc, and topological_ordering.cc. They are really basic, but useful examples, and they are ready to add to the branch (see #81).

4. The references in the doc should be checked: there shouldn't be unresolved ones (or not to many).

5. All of the \todo commands should be removed form the codes. The simplier ones should be done, the others should be noted in tickets.

[Alpar Juttner]

Replying to kpeter:

1. Related pages, that would be nice to port:
   • Named Parameters (there are a lot of reference for that, e.g. in bfs.h, dfs.h, dijkstra.h)
   • How to start using LEMON, Getting Started (they should be revised and maybe merged)
   • Quick Tour to LEMON (it contains some features that won't be part of the 1.0 release, e.g. LP, so maybe it would be better to postpone the port of this page)

We have a separate repository for the LEMON Tutorial. These should probably go there.

2. The modules page should be revised.
   • The name of the groups are inconsistent (e.g. "Path structures", "Graph structures", but "Maps"; using capitals in titles is not consequent; etc.).

Let's fix it.

• I would prefer a new arrangement in which a module contains either submodules or elements (i.e. classes, functions etc.), but not both. E.g. In Maps module there are two sections: "Graph Maps", "Map Adaptors", so reading the modules page a user may think that all of the maps are either graph map or map adaptor. I suggest an other section called "Other Maps" or something similar. It would cause a more logical and clear list of modules that can be used like a "table of contents" for LEMON.

I cannot see why it is better to have a lot submodules called "Other Xyz" instead of just putting their contents into the parent modul.

• In a separate branch the empty modules should be removed.

In fact, this was the original subject of this ticket. We must do it immediately after the release branch has been created.

3. Since we don't have tutorial yet, a few demo programs would be important in the 1.0 release.

In no way. Everybody is welcome to improve the tutorial (which is currently virtually empty), but at the current phase of lemon-1.0 I do not want to include any new code of unclear aims or potentially raising new open issues.

4. The references in the doc should be checked: there shouldn't be unresolved ones (or not to many).

Another one of original subjects of this ticket. We must do it immediately after the release branch has been created.

5. All of the \todo commands should be removed form the codes. The simplier ones should be done, the others should be noted in tickets.

Yes, a patch for this is very welcome.

[Alpar Juttner]

Replying to alpar:

Replying to kpeter:

1. Related pages, that would be nice to port:
   • Named Parameters (there are a lot of reference for that, e.g. in bfs.h, dfs.h, dijkstra.h)
   • How to start using LEMON, Getting Started (they should be revised and maybe merged)
   • Quick Tour to LEMON (it contains some features that won't be part of the 1.0 release, e.g. LP, so maybe it would be better to postpone the port of this page)

We have a separate repository for the LEMON Tutorial. These should probably go there.

I was wrong here, a revised and probably more technical version the "Named Parameters" page should be a part of the doc.

[Alpar Juttner]

Replying to alpar:

I was wrong here, a revised and probably more technical version the "Named Parameters" page should be a part of the doc.

I created separate ticked for this, see #147.

[Peter Kovacs]

Replying to alpar:

Yes, a patch for this is very welcome.

I created separate ticked for this, see #149.

[Peter Kovacs]

[9db8964f0cf6] removes several doxygen warnings. It should be applied into the main branch as well as the 1.0 brnach.

[Peter Kovacs]

[64f8f7cc6168] fixes more warnings. It should be applied to the main branch.

[Peter Kovacs]

[2cc60866a0c9] reorganizes the modules section and removes the doc of all tools in the lemon/bits directory. It depends on [64f8f7cc6168]. It should went to the main branch, too.

[Peter Kovacs]

[3a2e0692eaae] removes all references to tools that have not yet been ported.

[Peter Kovacs]

After applying [2cc60866a0c9] (to both branches) and [3a2e0692eaae] (to the 1.0 branch) I think the doc is practically clarified.

However it seems to be stange now, that the first reference in the "How to read the documentation" section is for the demo programs, since we have only three of them, and they not really representative or typical. So maybe this line should also be removed.

[Peter Kovacs]

[2cc60866a0c9] went to the main branch, [3a2e0692eaae] went to the branch 1.0, and the last several changesets of the main branch were merged into the branch 1.0.

However the merge [12626fc94ccf] in branch 1.0 seems to be faulty, at least in the file doc/groups.dox. The attached patch [2592532ee838] fixes this file, but it would be important to check whether other files are merged correctly or not.

The other patch [1e2d6ca80793] contains several doc improvements on the head of the main repository. It should be applied to both branches.

[Peter Kovacs]

I think we can close this ticket.