Mirror of the Rel4tion website/wiki source, view at <http://rel4tion.org>

Clone

HTTPS: git clone https://vervis.peers.community/repos/yEzqv

SSH: git clone USERNAME@vervis.peers.community:yEzqv

Branches

• master

Tags

old.mdwn

Use this as basis: https://wiki.gnome.org/MaintainersCorner/

inside .ikiwiki

[[!iki tips/inside_dot_ikiwiki]]

project page, doxy pages and readme generation

Useful things, even for maintainers in general:

• http://svn.savannah.gnu.org/viewvc/trunk/util/gendocs.sh?root=texinfo&view=markup
• http://www.gnu.org/prep/maintain/maintain.html

Example for page of GNU project:

• http://www.gnu.org/software/autoconf/

The idea is as follows.

To make it easy to keep the order in FTP, there will be 4 main directories which will map to wiki pages and fill the following purposes:

• readme: Collects extracted partial READMEs of all projects, mainly for inlining into each project’s main page. Or maybe a different setup, see below.
• internal: Collects compiled HTML full reference pages of all (minor?) releases of all program and library projects that have code reference.
• manual: Collects compiled manuals in several formats (like on GNU’s website, check their gendoc script) of all projects that have manuals. For libraries it’s usually doxygen-made API reference and tutorial.
• manpages: Collects all manpages of all projects that have them

Since these are generated and not manually made, it may be a good idea to put them in a separate underlay, maybe not in the FTP server. Currently they have a separate underlay, /home/ikiwiki/generated.

readme

My first idea was to inline the package READMEs into the website. But there is a major weakness: Nothing in them generated automatically. Each package will have its own README in version control, even if they have many common parts. After realizing I can generate the common parts, I had a new idea: Have a readme page on the wiki, possibly using templates for the common parts. The package README will simply be generated from it.

That, of course, is a problem too - people should always have a full README in the package. Would it be copied manually or automatically? How to avoid cluttering the git log with minor README type fix commits?

Then I checked GNU’s ones and I realized the thing is that they are separate files. The content is not copied around or generated. Each maintainer simply knows they need to update both the README and the project page.

Therefore, by default, this must work: Manually written separate files. When each package has its own maintainer, it’s reasonable effort. On the other hand, I’m working alone right now and many new packages will come, so saving work by automating things may be a good idea.

Another option is to have SOME readme sections in git, and the rest generated when building.

The general direction should probably be having an option to save work by:

1. Having template-generated parts in the project page
2. Having README-extracted parts in the project page
3. Having a template for a new project, including README
4. Having build-generated parts in README

Let’s examine autoconf and sif, and compare.

autoconf readme

• description
• dependencies
• common files and their roles (INSTALL, COPYING, etc.)
• mailing lists
• licensing
• copyright notice

autoconf page

• description
• downloads: http, ftp, CD, git clone, git browse
• documentation
• mailing lists
• related software
• reporting bugs
• maintainers
• humor

sif readme

• description
• downloads
• mailing list and IRC
• directory structure
• versioning scheme, news and changes files
• license
• installation
• dependencies
• reporting bugs
• hacking
• submitting patches

some drafts from sif wikipage

This is supposed to be the webpage of Sif. It’s supposed to have:

1. An HTML rendering of (parts) of README
2. An HTML rendering of the API reference, along with the tutorial etc.
3. Development/other info and plans

The parts from README will probably be right at the address of this page, but not necessarily by putting the README in underlay - it will be in underlay as a subpage, and will be [[ikiwiki/directive/inline]]d here.

The 2 first kinds will be made with a script and written into the website:

• The (parts of the) README will be in the FTP underlay, rendered to HTML by ikiwiki like the git-managed pages
• The API reference HTML will be built from source and either put in some kind of underlay/overlay using ikiwiki features/plugins, or on a dedicated domain like dev.partager.null.

Note that the API reference will need to be there at the same time for all releases, and there will need to be symlinks like “stable” and “latest”. The main page for each reference will contain a list of the available versions present. It can either be done using ikiwiki manually by adding links to the source with a script and manually git-pushing the result, or the final HTML can be generated externally, separate from the wiki source and automated: e.g. detect versions by looking at folder contents instead of a manually managed list.

I could use ikiwiki template pages for that, to help automate and generalize.