Rel4tion-Wiki/maint/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-push`ing 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.