Re: [Gnu-arch-users] log headers

[David Allouche]

On Fri, 2004-10-15 at 13:57 +0200, Albert Reiner wrote:
> Hi,
> 
> in the ++log.category--branch--version--... file I get from `tla
> make-log` there are header fields Summary and Keywords.
> 
> Sometimes I wonder whether these work like in e-mail headers, i.e.,
> 
> - whether I can continue a long entry on the next line, provided it
>   starts with some leading whitespace;

Yes. This file (that I call "log message") is used to generate the
revlog (revision log, aka patchlog) file for the created revision. The
revlog file format is (essentially) rfc822.

> - whether there needs to be an empty line between the last header
>   field and the beginning of the regular text;

Yes.

> - and whether I can just add my own X-Something headers if I want (not
>   that I would know right now what I might want it for).

Yes.

> Currently I leave an empty line, and I squeeze everything on a single
> line per header.

Works as well. I personally find it simpler and more reliable, since you
can expect that some third party tools will not cope well with
multi-line summaries.

It is even likely that tla itself does not cope well with that (e.g. the
-s option to logs or revisions), but in my opinion that would be a bug.

> Also, how do I access those fields?  The Summary I can get with `tla
> revisions -s`.  What about the keywords?  And the full text of the log
> entry?  And the X-Something header if it is allowed?

tla cat-log            reads from the current tree
tla cat-archive-log    reads from the archive 
tla library-log        reads from the the revision library

> I suspect all this is documented somewhere, but I haven't found
> anything.  Where should I have looked?  (BTW, I would prefer a simple
> man page by far to the `tla command -H` system.)

If it's not documented on the wiki (I have not checked), that would be a
good place to add the documentation you were missing. Consider the time
you spend writing it a retribution for the time the community spends
helping you.

Improving the built-in documentation is another issue entirely, you
should probably start by looking in the mailing list archives (there was
a discussion recently about that, keyword "tla help") then start a new
thread with concrete suggestions.

> Thanks for any pointers,

http://wiki.gnuarch.org
http://lists.nongnu.org/archive/html/gnu-arch-users/

-- 
                                                            -- ddaa