firebird-docs

[Firebird-docs] manual module

[Tilo M. <tm...@al...>]

Hi all,
I have committed the updated Docbook setup. Be aware that all files (except
the .zip archives) in the directories ./src/docs/docbook and
./src/docs/docbookx still need to be purged from CVS.

Regards,
Tilo

Re: [Firebird-docs] manual module

[Paul V. <pa...@vi...>]

Hi Tilo, and all,

> I have committed the updated Docbook setup. Be aware that all files
> (except the .zip archives) in the directories ./src/docs/docbook and
> ./src/docs/docbookx still need to be purged from CVS.

I ran into some trouble initially because the zip in src/docs/docbook
creates its own subdir when unpacked. From there I had to move
everything up one level.

Here's a step-by-step for people who want to have a correctly set up
manual module:

1. Checkout the manual module from CVS.

2. Go the the src/docs/docbook subdir, and delete all files and
   subdirs there EXCEPT docbook-xsl-1.60.1.zip

3. Unzip docbook-xsl-1.60.1.zip to src/docs/docbook (the current dir).
   This will create a new subtree docbook-xsl-1.60.1 within
   src/docs/docbook

4. Go to this new subdir docbook-xsl-1.60.1 and move everything in
   there (files and subdirs) up one level, i.e. to src/docs/docbook

5. Delete the now-empty subdir docbook-xsl-1.60.1 after having left it

6. Now go to the src/docs/docbookx subdir of the manual module. Delete
   all files and subdirs there EXCEPT docbkx412.zip

7. Unzip docbkx412.zip to src/docs/docbookx (the current dir). This
   will create a number of files and subdirs within src/docs/docbookx;
   don't move those, they are in the right place.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] manual module

[Tilo M. <tm...@al...>]

Hi Paul,

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@s4......
> Hi Tilo, and all,
>
> > I have committed the updated Docbook setup. Be aware that all files
> > (except the .zip archives) in the directories ./src/docs/docbook and
> > ./src/docs/docbookx still need to be purged from CVS.
>
> I ran into some trouble initially because the zip in src/docs/docbook
> creates its own subdir when unpacked. From there I had to move
> everything up one level.

You are right, maybe we should move the zip one dir up?

BTW: I'm not quite sure that putting zips in CVS is a good policy, but I
think it is much more convenient.

> Here's a step-by-step for people who want to have a correctly set up
> manual module:
>
> 1. Checkout the manual module from CVS.
>
> 2. Go the the src/docs/docbook subdir, and delete all files and
>    subdirs there EXCEPT docbook-xsl-1.60.1.zip
>
> 3. Unzip docbook-xsl-1.60.1.zip to src/docs/docbook (the current dir).
>    This will create a new subtree docbook-xsl-1.60.1 within
>    src/docs/docbook
>
> 4. Go to this new subdir docbook-xsl-1.60.1 and move everything in
>    there (files and subdirs) up one level, i.e. to src/docs/docbook
>
> 5. Delete the now-empty subdir docbook-xsl-1.60.1 after having left it
>
> 6. Now go to the src/docs/docbookx subdir of the manual module. Delete
>    all files and subdirs there EXCEPT docbkx412.zip
>
> 7. Unzip docbkx412.zip to src/docs/docbookx (the current dir). This
>    will create a number of files and subdirs within src/docs/docbookx;
>    don't move those, they are in the right place.

Hopefully the purging of the obsolete files and dirs will take place quite
soon.

Regards,
Tilo

Re: [Firebird-docs] manual module

[Paul V. <pa...@vi...>]

Hi Tilo,

>> I ran into some trouble initially because the zip in
>> src/docs/docbook creates its own subdir when unpacked.
>> From there I had to move everything up one level.

> You are right, maybe we should move the zip one dir up?

Then it would still create a wrongly named subdir and you'd have to
move everything sideways instead of up...

> BTW: I'm not quite sure that putting zips in CVS is a good policy,
> but I think it is much more convenient.

Indeed "cvs add" is much more convenient if you have two zip archives
instead of 1400 loose files, both text & bin :-)

But I think if people want to help writing docs, the least we can do
is give them a module that works out of the box.

Let's not forget that CVS may already be a hurdle for some people;
also they may have to set up Java, and last but not least they may be
totally unfamiliar with DocBook. If they go through all this trouble
only to find themselves with a broken build, this may just be too
much. But even for ourselves, it's nicer if a checkout "just works".

I don't know if you have some smart CVS frontend that can add multiple
files in one go; I'm pretty sure you don't feel like typing 1400 file
names; and I know you have very little time. If you like I can write a
little program or Perl script to traverse the dirs that the unzipped
archive generates, adds them to CVS if necessary, and also adds the
files they contain, deciding if they're txt or bin based on their
extension. I can try it out on my local repository and send it to you
if it works.

> Hopefully the purging of the obsolete files and dirs will take place
> quite soon.

I don't understand this. Doesn't "remove" work on SF? Once something
is removed to the Attic, why do you care how soon it is purged? Or
does it take a support request just to do a remove?


Greetings,
Paul

Re: [Firebird-docs] manual module

[Tilo M. <tm...@al...>]

Hi Paul

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@s4......
> > You are right, maybe we should move the zip one dir up?
>
> Then it would still create a wrongly named subdir and you'd have to
> move everything sideways instead of up...

So let's move the archives one dir up and point the users to the ReadMe file
;)

> Indeed "cvs add" is much more convenient if you have two zip archives
> instead of 1400 loose files, both text & bin :-)
>
> But I think if people want to help writing docs, the least we can do
> is give them a module that works out of the box.

I think we can't provide an out of the box solution. Remember Java, the env
variables, CVS, SSH, etc.

> Let's not forget that CVS may already be a hurdle for some people;
> also they may have to set up Java, and last but not least they may be
> totally unfamiliar with DocBook. If they go through all this trouble
> only to find themselves with a broken build, this may just be too
> much. But even for ourselves, it's nicer if a checkout "just works".

I handle it using two dirs, one in which I do all my CVS commands and
another dir in which I'm actually working. This way you are able to separate
all files which might be generated during the build process from those who
actually should go into CVS. So in your CVS dir there are the archives and
in the working dir reside the extracted files.

> I don't know if you have some smart CVS frontend that can add multiple
> files in one go; I'm pretty sure you don't feel like typing 1400 file
> names; and I know you have very little time. If you like I can write a
> little program or Perl script to traverse the dirs that the unzipped
> archive generates, adds them to CVS if necessary, and also adds the
> files they contain, deciding if they're txt or bin based on their
> extension. I can try it out on my local repository and send it to you
> if it works.

Take a look at "cvs import", this way you can bring in a whole bunch of
files.

> > Hopefully the purging of the obsolete files and dirs will take place
> > quite soon.
>
> I don't understand this. Doesn't "remove" work on SF? Once something
> is removed to the Attic, why do you care how soon it is purged? Or
> does it take a support request just to do a remove?

When something goes to the Attic you need to do a "cvs remove", but with
that huge amount of unneeded files it's much easier when SF do it.
BTW: Removing dirs from CVS is IMHO only an option for CVS admins.

> Greetings,
> Paul

Regards,
Tilo Muetze

Re: [Firebird-docs] manual module

[Paul V. <pa...@vi...>]

Hi Tilo,

>> Then it would still create a wrongly named subdir and you'd have to
>> move everything sideways instead of up...
>
> So let's move the archives one dir up and point the users to the
> ReadMe file  ;)

We ought to edit the Readme then, to give very clear instructions. If
we keep the zips in CVS, I think it would be best to rezip the one
that now unpacks to a "wrong" directory -- to make it so that if
people unzip the archives where they are, the contents land in the
exact right place.

>> But I think if people want to help writing docs, the least we can
>> do is give them a module that works out of the box.
>
> I think we can't provide an out of the box solution. Remember Java,
> the env variables, CVS, SSH, etc.

That's right, we can't save anybody from that. But we could at least
make it so that a checked out manual module works without further
adjustments. OK, except maybe two easy unzips (although I would
personally prefer to have those things unzipped in CVS).

>> I don't know if you have some smart CVS frontend that can add
>> multiple files in one go; I'm pretty sure you don't feel like
>> typing 1400 file names;

> Take a look at "cvs import", this way you can bring in a whole bunch
> of files.

You're right! I never knew that use of import; thought it was only for
the initial import into CVS.

>> I don't understand this. Doesn't "remove" work on SF? Once
>> something is removed to the Attic, why do you care how soon it is
>> purged? Or does it take a support request just to do a remove?

> When something goes to the Attic you need to do a "cvs remove", but
> with that huge amount of unneeded files it's much easier when SF do
> it.

Unless you have that nice graphical frontend ;-)

The advantage of "remove" is that you can do it yourself and that it
works instantly, so you have all the unwanted stuff out of the way
immediately. If you don't want it to occupy disk space at all, you can
have the admins ask SF to purge it from the Attic. (A disadvantage of
purging is that you lose a piece of project history.)

> BTW: Removing dirs from CVS is IMHO only an option for CVS admins.

I think you're right.


Greetings!
Paul Vinkenoog

Re: [Firebird-docs] manual module

[Paul V. <pa...@vi...>]

Hi Tilo,

> I don't know if you have some smart CVS frontend that can add
> multiple files in one go; I'm pretty sure you don't feel like typing
> 1400 file names; and I know you have very little time. If you like I
> can write a little program or Perl script to...

Meanwhile I've taken another look at WinCVS. This frontend allows you
to select multiple files and add/remove/commit them as a bunch, with
one button click. But you have to do txt and bin separately.

Maybe we also ought to have a look at TortoiseCVS, which Helen
recommended. If Linux users set up a dual boot system just to be able
to use that, it must be something worthwhile!

Myself, I also like the command line, but one thing it doesn't give
you is oversight. And adding a large number of files is an act of
masochism with plain command line CVS.


Greetings,
Paul