Re: [Mingw-cross-env-list] What happened to version numbers?

[Volker Grabsch]

Tony Theodore schrieb:
> On 23/04/2012, at 9:57 PM, Volker Grabsch wrote:
> > Although I don't want to go back to generating docs, I see
> > some other ways to move the version numbers back to *.mk:
> > 
> > 1) Don't show the version numbers in the docs, providing
> >   a plain package list.
> > 
> > 2) Show the version number in the package list, but generate
> >   it via a small JavaScript snipptet which reads and parses
> >   the src/*.mk files.
[...]
> I spent some time looking at Jekyll, the github pages templating
> system, but it did look like it was very flexible. I also considered
> commit hooks to rebuild the docs, but that's really overkill.

I also thought about using Jekyll, but it would solve the problem
only partly. We'd have an auto-generated website, but incomplete
docs in the repository. In comparison, the JavaScript approach
would also ensure up-to-date version numbers in the local docs.

> We could set the dependencies in the Makefile so that 
> 
> all: doc
> doc: $(PKGS)
> 
> This way the docs would be updated at the end of every successful build, git 
> wouldn't detect unnecessary changes, no-one would notice the few seconds at 
> the end, and updates to other parts of index.html can still be done without 
> affecting any other part of the build. We'd have up-to-date static docs all 
> the time with zero effort.

That's a good idea, but it still has some moving parts in it.
The current issue is that it's counter-intuitive to have the
package version in the docs. Thus, having the index.html suddenly
changed after a successful build will be counter-intuitive, too,
and may lead to incomplete patches/pull-requests. (i.e. the user
modified multiple package files, wants to commit one of then,
and thus commits only those files he thought he had changed)

Or, imaging a user updating a package version, committing it,
running a build to be sure, and then pushing (without noticing
that index.html changed meanwhile).

Those aren't big issues, but I'm afraid we'd replace one
small trap with just another small trap.

That's why I think it's worth to try to leave doc generation
completely out of the Makefile. The nice thing about the
JavaScript approach is that it requires no redundancy, as the
docs "generation" is "moved" from the Makefile into the browser.

> In the future, it would be nice to have more than a list of packages and 
> versions - I'm thinking of extra columns to show the supported targets. This 
> would be very difficult to maintain by hand, and is ideally suited to 
> automatic generation.

Indeed, that's the future - no matter which way we're doing it.
So that's a good argument against my proposal 1), and also a
good argument to move back the version numbers to *.mk in any
case.

Oh, one more point: We could also show which packages have
test programs, encouraging people to provide more of them.

Oh, and we could show the build commands as well as the test
programs in some kind of accordeon view. Okay, this would
require more than 5 lines of JS, and almost certainly a JS
library like ExtJS. So that's very far in the future. The
KISS approach would be just linking to GitHub's source view. ;-)


Regards,
Volker

-- 
Volker Grabsch
---<<(())>>---