r7678 - in trunk/BOOK:

Randy McMurchy randy at linuxfromscratch.org
Sat Dec 27 19:30:29 PST 2008


Bruce Dubbs wrote:

>    It wasn't a typo.  The date of the render will be approximately 0230 on the 
> 28th.  The changes were added on the 27th.  I can change my algorithm to set the 
> book's date to the date of the last change log entry if you really want.

Long ago as a reader and user of the book, and one that looked
at the date of the render against the date of the ChangeLog,
it was always confusing to me when they differed.

I'd wonder what was changed that wasn't annotated in the
ChangeLog. You'd then have to go to the -book mailing list or
the on-line html sources (Trac,CVS,whatever) to see what was
changed.

You'd find out what was going on sooner or later. Now, in the
case of today, one would look at the ChangeLog and see that
Bruce updated something in the PCI-Utils package on the 27th,
but the rendered book says the 28th. What was changed on the
28th to cause a difference not annotated in the ChangeLog?

In the case of today, NOTHING. Hence, the confusion. One would
look at the commit and say "Oh, Bruce changed the date of the
book, but used the old date for the changes he just made."

It doesn't make sense. The dates should be consistent. If you
update the render date in the same commit that you update the
ChangeLog, the dates should match.

I realize you've always looked at this differently, but that's
because you've been an Editor too long and not a reader of the
book. I remember being a simple reader/user of the book and
it was confusing. I'm trying to avoid that for others.

There's nothing gained updating the render date but not the
ChangeLog. It is nothing but confusing. Your way Bruce, the
book should then be rendered every day (with the render date
updated) to be consistent.

Some days the ChangeLog matches the render date, others it
doesn't and it is confusing to the novice. We can avoid this
confusion by simply making the render date the same as the
date of the ChangeLog entry.

Bottom line is, I think the book should reflect a date where
there was actual changes on it. In the case of today, you see
that the ChangeLog has one date and the render is incremented,
yet no change from the last entry that updated the ChangeLog.

Sorry for the rant. Hopefully, you see somewhat what I'm
trying to say. If not, don't worry about it.

-- 
Randy




More information about the blfs-book mailing list