Re: AUTHORS material (re)started

[Graham Percival]

On Fri, Dec 04, 2009 at 09:10:18AM +0000, james wrote:
> Graham Percival <graham <at> percival-music.ca> writes:
> > Sorry, now I'm doubting this.  I've realized that we have lots of
> > other links on the web page without spelling them out like this.
> > Updating them all would be a fair-sized job, and there's no reason
> > to single out this page.
> 
> Let me know what a 'fair-sized' job means. If it's a 'take a load of files 
> open
> them in an editor and search/replace then open another file and another and
> another', then that's fine I can do that (I know it sounds dull, but I'm ok 
> with
> this tidying up kind of job', maybe make it another 'to do' and assign it me -
> as long as I know what files or roughly where, we can start making the
> consistencies from now if you like?

There's two parts:
1. decide what it should look like
2. make it look like that.  (this isn't doable with
search/replace)

For example, consider the Contact page.  If we wanted to remove
the _link text_ from all external links, the
  user achive1 archive2 archive3
wouldn't fit onto one line.

Is that a problem?  Would it make the page look more cluttered,
harder to read, etc?  What about all the links on Publications, or
Introduction->Productions?  Where would we put all the http://
links -- at the beginning of each list item, or the end?  How
would that look?

Although we *do* have people who print the pdfs, there aren't that
many of them... and for something relatively unimportant like the
Productions page, it's probably not worth writing out the http://
lines directly.  The *vast* majority of people will only see the
page as html, and common practice is to display _Mercury Baroque_,
instead of http://www.mercurybaroque/02/02109.aspx

Another option would be to add 
  @iftex
  @uref{http://www.mercurybaroque/02/02109.aspx}
  @end iftex
material to the doc source -- these are only used when generating
a pdf.


But again, it's a fair-sized job, with quite little payback.  If
you're looking for more work, might I recommend issue 862 ?  It's
a high-priority job that should only take 15 minutes.  :)

More generally, issue tagged with Frogs is a good candidate for
busy-work.  I'll be adding more such issues in the next few weeks,
too.

> > That said, I'm not fond of the alternate "Name" vs.
> > "@email{blah,Name}" vs. "@uref{blah,Name}".  Maybe we should
> > specify either "Name" or "@email{blah,Name}" (as appropriate),
> > with a separate "(@uref{blah,website}): " after the first string
> > if they want a website listed?
> > Any ideas?
> 
> I don't have any ideas yet as this is the first time I've done this kind of
> thing and have nothing to compare so again, if you want to start making some
> 'from now on let's make it like..' consistencies, then do it, I can go back 
> and
> redo the edits.

Ok.  There's now four different possibilities for the author names:
-----
Graham Percival:
blah blah

@address@hidden,Graham Percival}:
blah blah

Graham Percival (@uref{http://percival-music.ca,website}):
blah blah

@address@hidden,Graham Percival}
(@uref{http://percival-music.ca,website}):
blah blah
-----

Use whichever method is appropriate for the author in quesiton.

> > I'm still fairly confident about my other instructions, although
> > if anything seems questionable, please question it!  :)
> 
> No it seems pretty straight forward, what I will probably get wrong are things
> like knowing when/when not to 'git -r'

I would do this every time I sit down to work on stuff.  If you're
only editing basic-authors.itexi then it won't be necessary unless
I tell you do, but if you start editing other files, you'll want
to do this every time, before you start changing things.

> if I need to compile or not (as opposed to just working with the
> source files - whatever that actally means ;) ).

It would be good if you did
  cd Documentation/
  touch manual-name.texi   (or manual-name.tely, as appropriate)
  make
that does a quick check that the doc files are ok.  If you want to
see the pdf and HTML, then you'd do
  make doc

If you want to experiment with something like writing out http://
directly, then you should generate the HTML to see how it looks.
If you're just adding to the authors list or updating download
file sizes (#862), then you don't need to look at the output.


BTW, patches can be sent to me directly (privately).

Cheers,
- Graham