Re: If it is still unclear to someone...

On Tue, Mar 20, 2007 at 11:15:53AM +0000, Tuomo Valkonen wrote:
> On 2007-03-20, Joerg van den Hoff <[email protected]> wrote:
> > instead of calling `nroff -man some_file' you'd do `nroff -ms some_file'. so
> > it's really a question whether the ms-macros are too complicated to use (they
> > are'nt, maybe easier than '-man').
> 
> But can 'man' call it that way?

the original `man' did directly execute `troff -man' I believe. the variant coming 
with OSX/FreeBSD gives the following for

`man -d ion3':

(cd /opt/local/share/man && /usr/bin/gunzip -c '/opt/local/share/man/man1/ion3.1.gz' | /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | less -fR)


i.e. it actually pipes the manpage source first through `tbl' and than through

/usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c.

it boils down to selecting terminal output with -Tascii
and selecting the macropackage with -mandoc (which in turn branches
to `mdoc' or `man' macros whichever appropriate for the manpage source file).
another macro-package (tty-char) defines some characters.

if writing the tutorial (which actually need not be the complete story. why not
leave room for getting a 'real' manual a la `mutt'?) with `-ms' one would not
call

man tutorial.txt

but rather essentially replace `-mandoc' by `-ms' in the `groff' call used
by `man':

groff -Tascii -mtty-char -ms tutorial.txt

or actually probably:

groff -Tlatin1 -mtty-char -ms tutorial.txt.

that would be the whole difference. if tables are included one would do
the same thing as can be seen with the `man' pipe:

groff -t -Tlatin1 -mtty-char -ms tutorial.txt

(piping through `tbl' can be initiated by the `-t' flag of groff, too).

and finally pipe it through less -fR, of course.

so, if the tutorial is called via some keybinding or menu it does'nt matter.
if the user wants to view it from the command line it's of course inferior to
`man' since you would have to locate it in the `share' directory or whatever
and know how to view it (but that could be explained in a comment block at the
beginning of the file of course). but on the positive side: `ms'  is to `troff'
what  `latex' is to `tex', i.e. a comprehensive macro package allowing much
better control than the `-man' macros.

in case someone is interested (and it is not stripped from the mail) I attach a
small `ms'-tutorial which probably  is written with `ms' itself so you get an
impresssion (autonumbered sections, table of content, etc.) the ion3 manual
might look similar in the end.

> 
> > not important. but why do you find it necessary to have to equally easy/short ways
> > to get at the manpage (Mod1+F1 and F1<CR> (I actually use the latter)?
> >> tutorial and how to get to it in the welcome message.
> 
> No particular reason... but I don't think a tutorial should have
> a special reserved key, unlike a reference. Now, if there was a 
> statusbar reference or so, then Mod1+F1 would be the suitable key
> for that.
as I said, I rather think of it as the first chapter of the 'ultimate guide to
ion3' :-). so I don't really care whether it is reached via mod1+f1 or via
f12-menu (but still think one does not  need the ion3 manpage twice (mod1+f1 and
f1<cr>) in the keybindings.

I definitely would not like a permanently visible entry in the statusbar (it's
like all the "HELP" entries in main menues of applications: wasting valuable
space).


joerg