Steve and all,

On 2005 Jun 2 , at 10.19, Rankin, SE (Stephen) wrote:

>> I think this may be out-of-date information, as there doesn't appear 
>> to
>> be a `docs' component, and currently no provision for installing all
>> these non-application-specific docs.  Any feelings, anyone, on what we
>> should do here?
>
> Yes, I have mentioned that before, what happened to all the docs? Over
> to all you lot that made the decisions in CVS week I think.

I don't think there was a specific plan about the docs, since they 
seemed rather lower down the priority list than the rest of the stuff.

I suppose the issue divides into two: should these docs be built as 
part of `make world', and at what granularity; and how should they be 
distributed?

Best, I think, is to make each one of the documents a component, so 
that docs/sc/002, say, would be a component just like libraries/ast is 
a component.  This is the case currently for docs/ssn/078 and 
docs/sun/248 (shorter).  That means that each one could be listed, 
probably indirectly, in Makefile.in's ALL_TARGETS.  That just means a 
suitable few-line Makefile.am and configure.ac dropped into each of the 
docs/*/* directories.

That may or may not be a good way of distributing them, but that's a 
separate issue, and Steve could construct distribution tarballs 
containing either individual doc distributions, or a meta RPM for all 
the docs, which referred to the individual ones.  I don't think I'm 
being very clear here, but the point is that if the individual doc 
directories are components, then they're fairly flexibly decoupled from 
the details of how they're distributed.

>> I've been in touch with Tim Lister about the bug he reported, which 
>> was
>> essentially that there was no obvious documentation on how to rebuild 
>> a
>> CVS checkout after an update.  I think this points to a couple of
>> problems with the process, which might become more important now we're
>> probably moving towards a more open-sourcy way of looking after the
>> software.
>
> It is in the top of the cvs repository, isn't it? There is a pointer to
> the READMEs on the CVS page:

Yes, but the problem Tim reported was that the top-level README gave 
instructions about how to do `make world' for a completely fresh 
checkout, and mentioned nothing of the slight difference in rebuilding 
it after an update.  I modified the README, including a pointer to 
SSN/78, which was when I realised there wasn't a version of that online 
other than on my pages.

That in turn prompted a couple of other questions about the process as 
a whole.  What we have seems to work pretty well for us as we are now, 
but might work less well when there are fewer of us, and possibly not 
at all when there's noone looking after things at all.  Can we do 
anything about this?

Did you have any thoughts about the bugzilla points?  I think Tim's 
resolved buildsystem bug is still showing as open, and as a tcsh bug.

>> This is certainly the case, in the sense that nothing in the docs/ 
>> tree
>> is built or installed, only docs which are managed within other parts
>> of the tree.  Also, there's no SSN/78 at
>> <http://www.starlink.ac.uk/static_www/docs_d_SSN.html> -- ought there
>> to be, do you think?
>
> Does it build now, should I switch it back on as part of the nightly
> build?

I'm not aware of a committed version ever not building, apart from once 
in the last year when I committed a broken version.  Is there some 
problem I don't know about?

>  What happened to the makefile that generated all the PS and DVI
> docs for the online documentation, it was part of the DOCS package.

If it was part of the old build system, then it's gone, and would need 
to be redesigned for the current build system.

See you,

Norman


-- 
----------------------------------------------------------------------
Norman Gray  :  Physics & Astronomy, Glasgow University, UK
http://www.astro.gla.ac.uk/users/norman/  :  www.starlink.ac.uk