Re: [Boost-docs] Too many copies of graphics like boost.png?

Subject: Re: [Boost-docs] Too many copies of graphics like boost.png?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2009-12-10 16:11:15

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden]
[mailto:boost-docs-bounces_at_[hidden]]
> On Behalf Of Daniel James
> Sent: Tuesday, December 08, 2009 11:02 PM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] Too many copies of graphics like boost.png?
> 
> 2009/12/8 Paul A. Bristow <pbristow_at_[hidden]>:
> > I note that there are many copies of graphics files like boost.png - over 70
> > last time I looked - and rising!  And there are several others similar
images
> > like top, prev, next, draft ... that are used in almost every bit of
> > documentation.

Thanks for this helpful reply.

> 70? Are you talking about the sandbox? 

Well, yes, that's a major source of duplicates.

Is it a disadvantage that the structure of the sandbox stuff doesn't match the
main Boost release?  I can understand that there is a certain amount of chaos
there - from its name if nothing else ;-)  But it makes the transition from
work-in-progress to something that is easy for users to try-out difficult, and
leads to private web sites or the vault being used for this (using zips).

Would it be better if we had a separate structure for work that is good enough
users trying to use - perhaps even review ready?
There has been some discussion about this elsewhere - 'Incubator' has been
mentioned as  a name.  It should have a structure closely matching Trunk.
Documentation and example could use techniques as you show to ensure that the
.css and image files at BOOST_ROOT are used?

>If you download a zipfile you
> shouldn't need to place it anywhere special to view the documentation
> so they really should contain all the relevant images.

I suppose so :-(

But it this true for Quickbook docs, say?

> They don't necessarily need to check the graphic files into
> subversion, especially if they're just checking in quickbook sources.
> The images can be copied in as part of the documentation build. For
> example:
> 
> http://svn.boost.org/svn/boost/sandbox-tags/old-move/libs/move/doc/Jamfile.v2
> 
> Although I didn't actually bother with the boost.png file, I think
> that was just a broken image. It should be possible to copy that from
> boost root and set the location using the 'boost.image.src' xsl parameter.

Sounds good.  But it's still yet another copied file?

For example in Trunk, I've 843 .png files (after a build (with some errors) of
the doc jamfile).  Most of these are in svn.  Many replicates are in groups of
half a dozen or so, including at least one that is not in svn. 

(I've some half million files on my Windows system - and it increases the backup
time and space, and I suspect that Windows spends it whole life indexing them
(to judge from the ceaseless disk activity).    

This has left me somewhat confused, but I get the impression that I am not alone
;-)

It might be useful to have some docs for doc writers on The Right Way to Handle
Images.  It would certainly help me :-)

But perhaps there are more exciting things to do...

> I have been meaning to reduce the number of copies of css files in the
> main repository. Occasionally someone will update a css file in
> 'doc/html' but not 'doc/src', but the documentation build overwrites
> the files in 'doc/html' so the change doesn't make it to the release.
> In this case, I think everyone should just use the original location,
> there's no need to copy files around when they're always available.
> But this is just one of the many things I never get round to.

Ah well I have an infinity of those ;-)

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal, UK   LA8 8AB
[phone], mobile [phone]
pbristow_at_[hidden]