Re: Hammer documentation

[Thomas Nikolajsen <thomas.nikolajsen@xxxxxxx>]

Sascha Wildner <saw@online.de> wrote:
> Thomas Nikolajsen wrote:
> > I think we should have a general introduction to Hammer for the release.
> > 
> > It could consist of:
> >  1) simple description of features
> >  2) simple examples of use
> > 
> > We already have a good deal of material in manual pages and Matts article.
> > But I don't think we have a general description of Hammer features in the manual pages;
> > it could go into mount_hammer(8) (mount(2) says FS info is in mount_FS(8)).
> 
> Some file systems have section 5 manpages, such as msdos or ffs (which I 
> prefer personally to the mount_*(8) strategy, but a slight problem would 
> be in this case that hammer(8) would get preference over hammer(5) when 
> doing 'man hammer').

I agree; other mount_FS(8) pages doesn't have general FS info either.
We could have hammer(5) and also hammer(7) as Matt suggested;
hammer(5) would then be a traditional man page with compact description of Hammer,
and hammer(7) would contain more free running text with uses cases as described below.

> >  - setting up disk: gpt, disklabel64 (or fdisk, disklabel)
> >  - formatting volumes: newfs_hammer
> >  - mount_hammer
> >  - snapshot
> >  - pruning
> >  - reblocking
> >  - adding volume
> > How can this be done?
> > When I just newfs_hammer another partition, it can't be mounted
> with existing: different fsid
> >  - mirroring
> > 
> > Is such a description already done?
> > Otherwise I will give it a try.
> 
> I have started on a hammer(5) manpage to give a general introduction to 
> the file system and its features. See
> 
> http://leaf.dragonflybsd.org/~swildner/hammer.5 and 
> http://leaf.dragonflybsd.org/~swildner/hammer.pdf
> 
> Take what you want, but generally HOWTO-like documentation should rather 
> go into the Wiki in my opinion because the manual pages are more a 
> reference than an introduction for newcomers.

Nice! Hammer(5) seems almost complete; it could be committed right away.
A reference to chflags(1) for nohistory could be nice.

I will look into hammer(7).

I don't know if it is considered to have hammer manual page in multiple sections;
will users find the? `man -a' really should be default (& `man -k' is your friend).

 -thomas