Re: Macro Archive Relaunch

[Guido Draheim]

Peter Simons schrieb:
> Compared to the old mark-up format, this has the following significant
> advantages:
>
>  - A short description of the macro (summary) is visible on the index
>    page.

I did try that lately too - but dumped it as it did clutter the index
page with information not really helpful. Do you have an example and
a guidelines helppage to show the benefits? In most cases the macro
name itself should be self-descriptive and it seems to be sufficient.

>  - Authors can be formatted into a real <a href="mailto:...";>name</a>
>    element on the web page.

Usual textual author reference does usually follow a common format that
can easily be recognized and turned into a mailto-href. Personally, I
do have some politic problems whether it is actually a wish of the
original author be scanned by bots, so I did decide not to turn that
feature on without asking each and every submitter.

>  - The description may include (a reduced set of) HTML 4.01 tags to
>    create fancier layout.

which can be helpful indeed.

>  - The synopsis may include <br/> tags to allow for multi-line
>    formatting.

which I never have been thinking of - if the synopsis happens to
be too long than something may be wrong anyway. In parts it stems
from the fact that the gnu ac-archive uses h2 tags - using some
smaller layout tags improves the situation, see the new style in
the sfnet ac-archive for reference.

>  - The submitter can decide into which category the macro is going to
>    be included (note the attribute "category") rather than me deciding
>    that.

That's a great thing - while it should be easy to do that with an
extra option for the old textual format as well (@category or some
such).

> The <name> tag, which appears to be pointless, is used to determine
> how the macro's file is to be called. It can be used to generate macro
> packages -- something many people have missed badly in the past.
> Effectively, you include multiple macros in the <m4source>, you
> describe them in the <synopsis>, <summary>, and <description> tags,
> and you set the <name> to something like "my_java_package" and there
> you are.

That might be not easy to grasp - I think you mean `macro bundles`
as to have multiple macros in one submission file, right?

> Of course, I can automatically convert macros from the old format into
> the new one. At the moment, though, I chose to retain all macros in
> the format in which they were submitted.

good. Do you start a new cvs with it? I have some automatic
routines to sync my branch with the gnu ac-archive's cvs
which would need to follow up with it. Since I'm doing xml
almost daily these day, I don't see a problem to blend the
new parts into the sfnet branch (as long as the sfnet branch
is needed, perhaps (hopefully?) it's obsolete some day)

> Having outlined this, let me come to the part where I beg for
> assistance. :-) I need help with the following tasks:
>
>  (1) Work out some cool layout, formatting, style sheet, etc.
>
>  (2) Major clean-up of the macro submissions included so far!
>
>      Some macros have been obsoleted by newer Autoconf versions, some
>      macros contain bugs or very poor formatting of the documentation,
>      and some macros are outright stupid. (Like a few of my own
>      submissions, which I removed with a slightly red head because of
>      the shame.)
>
>  (3) Clearly, the current set of categories is inadequate. We need to
>      work out a new categorization ... And then we need to
>      re-categorize the macros contained in the archive so far.

I did have another idea in this respect, since some macros might
be valid to live in two or more categories. In a way I was always
thinking of having a set of keywords for categorization and let
the macros be browsable by keywords - not much unlike the
software categorization at freshmeat or sourceforge.

>  (4) General ideas what to do and how to improve the archive.
>
>  (5) Set-up a mechanism how submitters can easily validate their XML
>      files. I would love to have a web-page where you just upload your
>      submission and get all errors produced by the XML validator back
>      right away. When the macro does not produce any errors, it should
>      be submitted into a queue right away for addition to the archive.
>
>  (6) Lot's of additional documentation must be written.
>
>  (7) Work out a good way to show a list of most recent changes. (We DO
>      have this information thanks to CVS, I am just not sure how to
>      visualize it in a good way.)
>
>  (8) Think of a good way to distribute the macros in a meaningful way
>      so that Linux distributions can include them. (I do have a
>      volunteer for creating RPM packages already, but I am just not
>      sure how to organize things in the release archive.)

The sfnet branch may have some hints here - it's been the primary
reason to split up since I did desperatly need packaging and transfer
of versioned files for my work. You did throw out the relevant parts
years back. AFAICS, rpms of the macros of the ac-archive do already
exist, it's just the topic of inventing a new one that fits in with
the new webpage style, right.

> This is certainly getting over my head by now (as some submitters have
> noticed by my poor response times) and I could really use some HELP!
> :-)

Yes, I had to make up a kill list so that my automatic sync-scripts do
not try to back-update macros where I have already the newer version
in the archive. As to critize here: quick and nice response to users
and their submission are much higher needed than great new software to
format the submissions. Let's hope you have some more time now for
your people, and of course nice documentation to make it easy for them
to get a benefit from the new format instead of being just burdened
with problems that thy don't actually have with an ac-macro - possibly
making the resistance level higher to actually submit a new ac-macro.

wish you well, cheers, guido                   http://ac-archive.sf.net
p.s. I own ac-archive freshmeat entry - please give me sign as to when
it is time to announce it to the world so that people can have a look.