Re: [Bashburn-info] man page

[Steven W. O. <st...@sy...>]

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.

Anders, I don't know what that thingy is in your name between the d and 
the r but it makes groff slightly upset. Maybe you should change your name 
;-)

Also, I deleted the .man file and the .1 file from the docs dir since they 
are now files that are made.

Look good?

-- 
Time flies like the wind. Fruit flies like a banana. Stranger things have  .0.
happened but none stranger than this. Does your driver's license say Organ ..0
Donor?Black holes are where God divided by zero. Listen to me! We are all- 000
individuals! What if this weren't a hypothetical question?
steveo at syslang.net