Re: [Bashburn-info] man page

[Nick W. <ni...@uk...>]

On Mon, 6 Oct 2008 14:25:13 -0400 (EDT)
"Steven W. Orr" <st...@sy...> wrote:

> On Monday, Oct 6th 2008 at 04:00 -0000, quoth Nick Warne:
> 
> =>On Sun, 5 Oct 2008 18:20:14 -0400 (EDT)
> =>"Steven W. Orr" <st...@sy...> wrote:
> =>
> =>> On Sunday, Oct 5th 2008 at 12:10 -0000, quoth Nick Warne:
> =>> 
> =>> =>On Sun, 5 Oct 2008 10:49:34 -0400 (EDT)
> =>> =>"Steven W. Orr" <st...@sy...> wrote:
> =>> =>
> =>> =>> On Sunday, Oct 5th 2008 at 05:56 -0000, quoth Nick Warne:
> =>> =>> 
> =>> =>> =>On Sat, 4 Oct 2008 21:53:46 -0400 (EDT)
> =>> =>> =>"Steven W. Orr" <st...@sy...> wrote:
> =>> =>> =>
> =>> =>> =>> I moved bashburn.1.gz to bashburn.1
> =>> =>> =>> 
> =>> =>> =>> I also did a bit of hacking in the manpage structure. I'm
> not =>> =>> great =>> at the macro usage but I did fix a few things.
> Let me =>> know =>> if you see =>> any problems.
> =>> =>> =>
> =>> =>> =>Steve, you should have said.  I have a man page template,
> and =>> the =>> =>bashburn man page gets created from that using sed
> wizardry =>> - that =>> way =>it is easy to change anything.
> =>> =>> =>
> =>> =>> =>http://anaturb.net/create_man_p.htm
> =>> =>> 
> =>> =>> Sorry, I don't understand. Is there a template somewhere?
> =>> =>
> =>> =>Yes, I have a bashburn template directory, so I edit the
> template =>> and =>then create the man page.
> =>> =>
> =>> =>I was wondering where it should go, as it should NOT be in the
> =>> release =>files, so I guess it could live in trunk only just for
> man =>> page edits, =>and just the man page itself gets moved over to
> release. =>> =>
> =>> =>Let me do some documentation and upload it anyway.
> =>> 
> =>> Now I see the problem. The content and shape of the src repository
> =>> has nothing at all to do with the content and shape of the
> released =>> code.
> =>> 
> =>> So.... If you have a script, or a body of software that should be
> =>> executed in order to generate a man page, then the man page itself
> =>> should not be checked into the repository at all. IOW, the file
> =>> bashburn.1 (.gz or otherwise) is not a file that was *written* by
> a =>> person. It's a file that was generated. (If you ever worked in
> the =>> ClearCase world, we would call such things "derived
> objects".) You =>> have some file which right now is sitting in Merry
> Old England and =>> that was used as input to something which
> resulted in bashburn.1 . If =>> you got hit by a bus then we'd be
> sitting on the .1 file, which =>> probably isn't a huge loss (the
> file, not you), but we'd have no way =>> to start from what you
> started from. =>> 
> =>> >From there, look at the Install.sh file after I modified it.
> There's =>> >no 
> =>> reason for the man page to be treated the same as every other
> file. =>> We can write exceptions, lots and lots of them if we want
> to. =>> 
> =>> So what you should do is to check in the real src code and the
> =>> script(s) you run to create the output man page. Make sense?
> =>> 
> =>
> =>OK, I moved the whole lot up - have a look and see what y'all think.
> =>
> =>Steve: I tweaked the man page a little more from what you done.
> 
> I just created a Makefile which when run will create bashburn.1 as
> output. The makefile has a bashburn.1 and a clean as a target. The
> Install.sh will automatically run the makefile to get the most
> uptodate bashburn.1. The file bashburn.man is deleted. There are two
> additional targets in the Makefile: bashburn.man and bashburn.ps
> (Note that they use the -pte options to groff.)
> 
> You can look at the bashburn.ps with some PostScript viewer like
> evince or gv. It's publication quality. The .man file is just plain
> text. There's a lot more to go to make the man page technically
> correct. I'm not *sold* on the idea of the bashburn.sed file as being
> less work to learn than learning
> 
> man 7 groff_man
> 
> but let's go with it for the time being.
> Also, I deleted the .man file and the .1 file from the docs dir since
> they are now files that are made.
> 
> Look good?
> 

Steve,

Great job.  Please also update BUILD_README file to to reflect changes.

This is very good.

Nick
-- 
Free Software Foundation Associate Member 5508