Re: Archive unification progress

[Tom Howard]

Hi Peter,

Peter Simons wrote:
> Tom Howard writes:
>
>  > 1) Exactly what meta data was the xml supposed to
>  > provide?
>

Sorry, my bad.  I meant what was it supposed to provide above and beyond
the plain text format.  Sorry if I'm being dense, but I just don't get it.

>  > 2) What is the exact plain text format at this point?
>
> The plain text format is the one your macros are marked-up
> in too, right now. It supports the tags @synopsis, @author,
> and @version for meta-data. All other "dnl ..." text is
> documentation, lines that are indented are block quotes.
> That's it. ;-)

Cool. I must have read this format somewhere, but I can't find it right
now.  Is it still up on the GNU site?

>  > 3) How does this differ from the sf archive format?
>
> sf.net has some experimental extensions (@copyright?), but
> I'm not sure what exactly those are and what they do. Guido,
> do you have a description of those tags somewhere?

Seeing as you said the XML format is dead, how about we create a unified
plain text format (I'm more than willing to work on the tool the
generate the html or xhtml/css).  Here is a suggested extendible format
in a bison'esc format.

dnl: 'dnl' | '#'

space : ' '

heading : dnl space '@' string

doc_line : dnl space string newline
         | dnl newline

synopsis : dnl space '@synopsis' space string newline

description:  dnl space '@desc' newline doc_line+

author: dnl space '@author' space string newline

version: dnl space '@version' space string newline

copyright: dnl space '@copyright' space string newline
        | dnl space '@copyright' newline doc_line+

category: dnl space '@category' space string newline

package: dnl space '@package' space string newline

license: dnl space '@license' space string newline
        | dnl space '@license' newline doc_line+

section : heading newline doc_line+
        | heading space string newline

macro : 'AC_DEFUN([' macro_name '],' newline '[' macro_contents ']'
newline '])dnl' macro_name

documented_macro : synopsis+ description section* version category*
package* author+ copyright* license* macro

What does everyone think? It's just something I whipped up in 10
minutes, so I'm sure it could do with lot's of feedback (don't be
gentle, I've got a thick skin).

>  > 4) Exactly what information do you want in the macro?
>
> Originally, I wanted a macro to contain all information
> necessary to implement the procedures described in:
>
>   http://www.gnu.org/software/ac-archive/policy.html
>
> Most of all, I wanted to allow dependencies and
> cross-references between macros.

I guess the best way would be to use the m4 code itself to check for
dependencies, otherwise handwriting the dependencies could become old
and out of sync.

If we get a unified format and archive, can we look at dependencies as a
second phase?  From what I can see neither archive has this feature, so
to me it doesn't make sense to make it a requirement of unification.

I assume by cross-references you mean a link to another macro.  Would
this just be for dependant macros or for other purposes as well?  If
it's for other purposes, can you give an example?

> Packages of macros have
> been a missing feature ever since, too.

I've put packages in the format, but I would suggest we wait and see how
they are used before doing any more.

>
>  > Now I assume you are using some automated tool to
>  > generate the html from the macro (I'm guessing this is
>  > where the haskal is coming in), correct?
>
> Yes, the software I use is written in Haskell. It reads the
> marked-up macro files and generates pretty much everything
> you see on-line at www.gnu.org/software/ac-archive at the
> moment.
>
>
>  > I've got some experience with php, so if I know the plain
>  > text format, I should be able to generate xhtml/css, the
>  > advantage being that php is readily available and can be
>  > used from both a web server and from the command line. Do
>  > you want me to give it a shot?
>
> I definitely welcome any help! I just think we'd need to get
> a grip on the markup format we'll use in the future first.
> If there ever was a chance to make changes and improve
> things, it would be now. ;-)

Cool.  Let's get the format discussion going, see what comes out and
talk about the tool after that.

>  > What specifically is preventing unification of the two
>  > archives?
>
> We are using different tools, have different priorities,
> already have different contents to some degree. I doubt
> we'll unify the two archives (as in: make sf.net obsolete)
> any time soon. The best we can do is to make sure both
> archives have the same content -- and even that is
> difficult, because that objective greatly limits the changes
> either one of us can make to the software.

The first step seams to be unifying the format and the tools.  Let's try
to get there first.

> Guido Draheim writes:
>
>  > Anyway, I am not sure whether a live representation via
>  > php is even allowed on the gnu webserver - the gnu
>  > webserver seems to be generally represented in a second
>  > CVS area at savannah.
>
> You are right, www.gnu.org does serve only static pages. All
> web contents is checked into CVS at Savannah, then it shows
> on the site some time later. No PHP, no CGI, nada.

That's fine.  What about cron jobs?  For http://sserver.sf.net we have
the web source in cvs and every hour or so a cron job checks it out onto
the web server.  We could use a similar technique to generate the html
from the macros in cvs and then place the generated html in the web cvs.
 The idea being that updating a macro in the cvs would auto-magically
update the web page.  How does that sound?

Cheers,

--
Tom Howard

Public Key: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x433B299A

tomhoward.vcf
Description: Vcard

signature.asc
Description: OpenPGP digital signature