DaemonForums  

Go Back   DaemonForums > Miscellaneous > General software and network

General software and network General OS-independent software and network questions, X11, MTA, routing, etc.

Reply
 
Thread Tools Display Modes
  #1   (View Single Post)  
Old 8th November 2008
TerryP's Avatar
TerryP TerryP is offline
Arp Constable
 
Join Date: May 2008
Location: USofA
Posts: 1,547
Default troff/nroff Q; how to put a linebreak in a tag labeled lists item

For a program I'm putting together, I've several flags that have both a positive and negative form (e.g. --foo, --no-foo) for things that are not implicitly set by other options. Each pair of options is done in both these forms + their corresponding short options where available. Each of which is described in a single paragraph, but I'm having trouble formatting the options.

Code:
.Sh OPTIONS
.Bl -tag -width indent
.\" The item in question
.It  Cm --interactive, -i Cm --non-interactive, -b
paragraph describing the options
.\" other options, several of which are like the above
.El
which produces just what you would expect:
Code:
 OPTIONS
      --interactive, -i --non-interactive, -b
              paragraph describing the options
but I would like the option flags to be shown as with a line break between the positive and negative forms of the option for legibilities sake, like this:

Code:
      --interactive, -i
      --non-interactive, -b
              paragraph describing the options
The first thing that occurred to me was to use the Pp macro in between, but that cuts off the second option, then displays the paragraph.

Code:
.It  Cm --interactive, -i Pp Cm --non-interactive, -b
paragraph describing the options


      --interactive, -i
              paragraph describing the options

I haven't been able to find anything by searching the web or in the mdoc(7) manual page. Before I end up splitting them up into separate list items, does anyone know how I might be able to do this?
__________________
My Journal

Thou shalt check the array bounds of all strings (indeed, all arrays), for surely where thou typest ``foo'' someone someday shall type ``supercalifragilisticexpialidocious''.
Reply With Quote
  #2   (View Single Post)  
Old 9th November 2008
DrJ DrJ is offline
ISO Quartermaster
 
Join Date: Apr 2008
Location: Gold Country, CA
Posts: 507
Default

Quote:
Originally Posted by TerryP View Post
Before I end up splitting them up into separate list items, does anyone know how I might be able to do this?
You break them into separate items. You can always force a line break with the raw troff command ".br" (without the quotes). One caveat: I've not used the mdoc macros, but what I suggest is generally what you would do.

You might also look at the ".Bd/Ed" command pair. It looks to be similar to the ".DS/.DE" pair in -ms. Displays do not need separate ".br" commands added -- line splits follow carriage returns (unlike most of troff, which reads characters without regard to line breaks).
Reply With Quote
  #3   (View Single Post)  
Old 9th November 2008
TerryP's Avatar
TerryP TerryP is offline
Arp Constable
 
Join Date: May 2008
Location: USofA
Posts: 1,547
Default

I tried the .br command as soon as I found it in my reference, but it displays a literal '.br' in the output.

Code:
.It Cm --interactive, -i .br Cm --non-interactive, -b
paragraph describing the options

      --interactive, -i .br --non-interactive, -b
              paragraph describing the options
Although I admit, for as much experience as I have with writing manual pages, I could just be doing it stupidly...


The .Bd/.Ed and .DS/.DE pairs seem to fulfill the same purposes from what I can see in the manuals, but .Bd/.Ed appear to require a bit more manual formatting then I have the skill to complete with troff right now. Looks like I'm going to be splitting them into separate list items for now.

Thanks DrJ
__________________
My Journal

Thou shalt check the array bounds of all strings (indeed, all arrays), for surely where thou typest ``foo'' someone someday shall type ``supercalifragilisticexpialidocious''.
Reply With Quote
  #4   (View Single Post)  
Old 9th November 2008
DrJ DrJ is offline
ISO Quartermaster
 
Join Date: Apr 2008
Location: Gold Country, CA
Posts: 507
Default

Quote:
Originally Posted by TerryP View Post
I tried the .br command as soon as I found it in my reference, but it displays a literal '.br' in the output.
Really? That's very odd. Did you put the .br as the first characters on a line? If you don't, then troff does not interpret it. It is that way for all raw troff dot commands.
Quote:
The .Bd/.Ed and .DS/.DE pairs seem to fulfill the same purposes from what I can see in the manuals, but .Bd/.Ed appear to require a bit more manual formatting then I have the skill to complete with troff right now. Looks like I'm going to be splitting them into separate list items for now.
Manual formatting? The block commands take what is on each line, and honor the line breaks when doing the formatting. That's the idea of using them.

I don't recall your original code, but if I remember properly, you put things on the same line to use the same font command. That's in general not good troff style. You want to use font commands that are independent of text location, so that you can move them around if you want. One way to do that, for example, is to use the raw troff \fB (or \fI) and \fP when you are done. That is the bold (or italic) font of the currently-mounted font family (like Times Roman), returning to the previous font (which usually is the "normal" one).

So if you use
Code:
.DS
\fBtext string 1\fP
\fItext string 2\fP
text string 3
.DE
you would get
Code:
text string 1
text string 2
text string 3
This of course uses the -ms block commands, but the man block commands are likely similar. If you did not use the block command, you would get
Code:
text string 1 text string 2 text string 3
which is not what you are after.
Reply With Quote
  #5   (View Single Post)  
Old 9th November 2008
TerryP's Avatar
TerryP TerryP is offline
Arp Constable
 
Join Date: May 2008
Location: USofA
Posts: 1,547
Default

Quote:
Originally Posted by DrJ View Post
Really? That's very odd. Did you put the .br as the first characters on a line? If you don't, then troff does not interpret it. It is that way for all raw troff dot commands.
I tried it both ways, inline it appears inline as expected (see my last posts code block), and on it's own line in the first column

Code:
.It --interactive, -i
.br
--non-interactive, -b
paragraph text
Which causes the the text after the .br to become part of the paragraph text instead of remaining as part of the list items tag. It seems everything thats not an argument to .It or causes a line break has this fate. Perhaps that's the nature of the .Bl/.It/.El arrangement in mdoc.


Quote:
Originally Posted by DrJ View Post
I don't recall your original code, but if I remember properly, you put things on the same line to use the same font command. That's in general not good troff style. You want to use font commands that are independent of text location, so that you can move them around if you want.
Fixed.

I am by no means familiar with troff syntax or common style conventions in formating the commands/macros. Unlike Tex/LaTeX most of what I know comes from reading existing troff files, figuring out what it means (where possible), then comparing the results of test cases to what was expected.


Quote:
Originally Posted by DrJ View Post
Manual formatting? The block commands take what is on each line, and honor the line breaks when doing the formatting. That's the idea of using them.
I know, I've just been unable to get the output formated the way I want. I'm very sure it's possible, I just don't know enough troff to pull it off intelligently yet.


I think it's time to steal a few nights off my usual study routines and properly inhale more documentation on troff, to fill out the gaps between what I know how to do in troff, and what I'll eventually need to do with it.the troff users manual should at least help in understanding the syntax better w/o writing test files.
__________________
My Journal

Thou shalt check the array bounds of all strings (indeed, all arrays), for surely where thou typest ``foo'' someone someday shall type ``supercalifragilisticexpialidocious''.
Reply With Quote
  #6   (View Single Post)  
Old 9th November 2008
J65nko J65nko is offline
Administrator
 
Join Date: May 2008
Location: Budel - the Netherlands
Posts: 4,125
Default

Why don't you just use this:?
Code:
.It Cm --interactive, -i 
.It  Cm --non-interactive, -b
__________________
You don't need to be a genius to debug a pf.conf firewall ruleset, you just need the guts to run tcpdump
Reply With Quote
  #7   (View Single Post)  
Old 9th November 2008
DrJ DrJ is offline
ISO Quartermaster
 
Join Date: Apr 2008
Location: Gold Country, CA
Posts: 507
Default

I don't know what to say about the .br issues. Usually you can intersperse troff commands with the macro packages, with some limitations. It depends on how the macro package is written. Since I've not used the man page macros, I'm afraid I can't offer many useful alternatives.

If you want to learn troff better, here is a place to look:

http://www.troff.org/papers.html

I'd suggest you start with the -ms macro package, as it is very simple and covers most of the practical document formatting requirements. From there, move to the preprocessors: tbl (for tables), eqn (for complicated math), pic (for line drawings), grap (for graphs), refer (for references) and chem (for chemistry). I don't think that chem is part of any of the BSDs -- I did a port for FreeBSD if you want it. Also keep in mind that groff has some extensions that are not part of the documentation, like .PSPIC to insert graphics elements into documents (in .eps format).

Also you might be interested in the TeX/troff thread that has popped up.
Reply With Quote
  #8   (View Single Post)  
Old 9th November 2008
DrJ DrJ is offline
ISO Quartermaster
 
Join Date: Apr 2008
Location: Gold Country, CA
Posts: 507
Default

Quote:
Originally Posted by J65nko View Post
Why don't you just use this:?
Code:
.It Cm --interactive, -i 
.It  Cm --non-interactive, -b
That would follow the troff idiom of using one command to do one thing.
Reply With Quote
  #9   (View Single Post)  
Old 10th November 2008
TerryP's Avatar
TerryP TerryP is offline
Arp Constable
 
Join Date: May 2008
Location: USofA
Posts: 1,547
Default

@J65nko that will create separate list items for each, it's not very pretty to look at either.

Thanks for the link DrJ, adding a few more documents to my reading list as I type this. I've seen some of them on other sites but not all :-) I originally started with BWKs tutorial, but I've got a copy of the troff users manual by Ossanna and Kernighan stored for inhalation. I'm the kind of person, that if I want to learn something - I go find (or ask for) a point of reference and start munching away at the task at hand; I love documents like these. I think it's more important to learn the troff side right now, so I actually know what is going on behind the scenes.

It seems that the ms and mdoc macro packages will be the meat and potatoes once troff is incorporated into my toolchain, but it can taste a little bit bland to skip the gravy, if you know what I mean DrJ.



@the TeX/troff thread, it interests me intently but more so in the reading-focused capacity, then offering comment in. You are arguably the most knowledgeable person on troff that I've encountered, and likewise OKO on TeX; you both have much more demanding needs of these tools then people like me and many more years of experience with them. Most of what I need done formatting wise, can be done in pure ASCII, aside from inserting images and tables in a /sane/ way.

It's one of my mid-term goals to properly reevaluate troff, TeX, docbook, and texinfo; and find where each belongs in my larger répertoire of tools.


--
Threads like this one we are posting in, are largely the difference between what I can learn on my own and trying to find the point at which the only way to go forward, is to go around another way; rather then keep walking into things.
__________________
My Journal

Thou shalt check the array bounds of all strings (indeed, all arrays), for surely where thou typest ``foo'' someone someday shall type ``supercalifragilisticexpialidocious''.
Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
The big TeX and (g)troff thread JMJ_coder General software and network 23 10th November 2008 01:19 PM
TeX for troff users? DrJ Off-Topic 0 2nd May 2008 09:29 PM


All times are GMT. The time now is 05:03 AM.


Powered by vBulletin® Version 3.8.4
Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
Content copyright © 2007-2010, the authors
Daemon image copyright ©1988, Marshall Kirk McKusick