Re: News about the macro archive

[Peter Simons]

Tom Howard writes:

 >> @license AllPermissive
 >
 > Sure I can, but can't I update the formatter instead? :D

If you care to write Haskell code. ;-)


 >> Yes, but editing the files manually isn't good enough.
 >
 > Um..  sorry if this is a stupid question, but why not?

If you look at the files in CVS now, you'll notice that they
are extremely consistent. They are all formatted alike,
there are no superfluous empty lines, the keywords are
ordered the same everywhere, etc. This consistency is
guaranteed by the formatting engine.

When the licenses are added to the m4 source, I want them to
be consistent too. They should be spelled the same way, they
should appear at the same place in all macros, they should
use the same formatting. Doing that manually is a lot of
work and probably bound to fail ... letting the tool do it
is a matter of calling

  genarchive m4src/*m4

and then it's done.

So it's my turn to ask a stupid question: Why do you want to
do the job _manually_ if all you had to do is to add
@license AllPermissive into the files and let a machine do
it?


 >> That's what my tool is doing, and I will run it once I
 >> know all macros are properly assigned.

 > But this (what I've added) means your tool doesn't need
 > to do anything regarding the licence, except generate the
 > appropriate html :)

No, that's not right. My tools spits out the m4 file in a
canonic version as well as the HTML files.


 >> So please just use @license for now.
 >
 > Well, :( if you definitely want to generate the licence
 > info, I'll get awk to swap over the one's I've already
 > done. Give me the nod and it's as good as done.

Yes, that would be nice. Thanks.


 > Why are you generating the m4 files for release?

I don't generate them "for release". I run them through
axlint as part of the build process before I commit them
into CVS, even. All macros you are seeing in the CVS
repository now are generated files in a way, yet they are
the authoritative files too. And axlint does a lot more than
just formatting: It enforces several points of the policy
(like Obsolete handling), it catches missing keywords,
misspelled keywords, malformatted arguments, etc. I only
commit my changes after axlint finds nothing more to do.
That's why the files are so consistent in CVS now, and
that's why I can distribute them in verbatim now.


 > I don't understand why you don't have the same m4 file in
 > CVS, tar.gz and on the website?

I do. The website even links directly into CVS for the
download.


 >> Yes, that would be great, but this is a secondary
 >> concern for me. The average everyday user can use the
 >> web site or download the release archives.

 > You might disagree with me on this (and let me know if
 > you do), but the more you allow the user to do
 > themselves, the less the maintainers need to do.

That's not my experience. For years the software to format
the entries was part of the release (macro2html.cxx and
genindex.pl), and it didn't make one bit a difference in
terms of quality of the submissions' markup. I had to edit
the submissions a lot back then, too.

I agree that it would be nice to distribute the tool chain,
but it's not my primary concern.


 > For instance, with the macros I submitted, you had to go
 > through each one and make the appropriate changes to make
 > it work with the html generator.

Where exactly did you have problems?


 >> I don't know. I have a pretty sophisticated software written
 >> already. Rewriting that in yet-another-language doesn't
 >> sound like an efficient use of resources to me.

 > But it wouldn't be a rewrite as we already have gendocs
 > to work from.

Let's put it differently: I _do_ have pretty sophisticated
software, and I will rather spend my time on improving that
than spending my time working on a different software. I
don't see the point. If you want to spend your time
improving gendocs.pl, then please go ahead. I can hardly
stop you, can I? :-) But the chances that I'll throw away
the system I have been developing for the last couple of
years in favor of a new one are slim, to put it carefully.


 > My main goal at for the ac-archive is to achieve
 > unification.

What exactly constitutes unification?


 > That is my driving force in my (current and future) work
 > in this project [...]. Now I fully understand and am
 > willing to accept that you have other primary
 > motivations, and I'm more that willing to help you
 > achieve these [...] so long as they don't threaten
 > unification [...].

Could you please outline the steps that you think should be
taken in order to further unification? What do you intend to
do in order to reach that goal? What do you expect me to do
in order to not stand in the way?


 > I'm already helping in terms of maintaining content by
 > doing the licence changes.

I know, and it is very much appreciated.


 > I'm also more than happy to [do the obsoletion of
 > macros].

A minor request: Since you do edit the macros for license
stuff anyway, could you watch out for macros that have the

  dnl obsoleted: some reason

line in them and turn that into

  dnl @obsoleted some reason

...? If nothing else, that will make it easier to identify
those macros that need to receive the AX_OBSOLETE treatment
later.

Another thing that would be _very_ nice is to break up

  @author person 1, person 2

lines into

  @author person 1
  @author person 2

..., because that will generate nicer copyright statements
when the time comes.


 > From what I understand, to make unification happen we
 > need to no longer generate the m4 files [...] and the
 > build system generates the docs (and does so on most
 > platforms) and installs the m4 files and the docs.

I'll comment on that once I know better what you regard as
"unification", okay?

Phew ... another long e-mail. ;-)

Peter