Re: Request for comments: prettify snippets page

[Graham Percival]

On Fri, 28 Dec 2007 10:51:30 +0100
John Mandereau <address@hidden> wrote:

> Le mercredi 26 d__cembre 2007 __ 07:06 -0800, Graham Percival a
> __crit : 
> > I'm honestly not certain that this tradeoff is worth it -- even
> > disregarding the amount of work involved.  What problem(s) is this
> > supposed to solve?
> 
> For example, t'd be a good thing to build a single
> Texinfo document (with .itelys) for all snippets, so we could easily
> get a single PDF and a single with all snippets sorted by categories
> (this is a user request IIRC), and a set of HTML pages with one
> category (or tag) per page, with easy navigation (we have this, but
> with no easy navigation); to achieve this, we should not use
> subdirectories.

Easy navigation could be achieved by spending 15 minutes editing
input/lsr/LSR.ly
and
input/lsr/*/AAA-intro.ly


The single PDF would be nice, and the HTML pages would be
identical to what we have already.  So the end result is a slight
positive.

> I'm ready to work on makefiles, makelsr.py and lys-to-tely.py to
> achieve this.  I think it's much more reasonable that my previous
> proposal, what do you think?

Yes... but...

I hate to be a wet blanket (I'm fond of this phrase: "the person
who stops other people from having fun"), but everything that I've
learned about documentation project management is screaming "not
worth the effort".

- the HTML would be identical to what we have already
- the current system works.  It wastes about 1 Kb of disk space /
  git tracker space.  If anybody cared about that, I bet I could
  save that much space by removing old comments from vocal.itely.
- it takes... what, and extra minute for building the docs?  Maybe
  5 minutes?  Again, IMO this is a minor issue.
- this would require changing LSR.  In my experience, any change,
  no matter how simple, takes at least one month.  While we're
  waiting for that change, you'll have a whole bunch of modified
  files in the build system ready for the new stuff, and I'll
  still be using the old build system.
- it would require $NO_CLUE amount of time and effort from you to
  implement the new system.
- it would require another $NO_CLUE amount of time and effort from
  you in $NO_CLUE weeks, after LSR has been updated, to fix/tweak
  the system.

If I were to add this to the GDP technical-todo list, it would be
in the MEDIUM section.  In other words, there are about 10
technical things that would improve the docs and which I am not
going to do, which are more important.  (and easier to do!)


If you can prove me wrong -- get Sebastiano to change LSR in two
days, whip up the python scripts in half an hour, and have
everything beautifully working before the new year -- then great!
But all of my experience on the docs and snippets suggests to me
that this will be a lot more work than you think.  :|
I therefore feel obliged to point out all the problems, in order
to potentially save you a lot of time/effort/frustration.

Cheers,
- Graham