Solved man man synopsis

C

Chris2000SP

Hi i'm wondering that Synopsis in man pages are not described. For a Unix beginner is that a little frustrating. If i'm blind tell me where i can found that information.

I have searched this in the internet but i thought it's offline available.

Thx
 
I'm not sure what you're asking for, but SYNOPSIS is the first section in every manpage (or second, if you count NAME as a section as well).

If you're looking for more in-depth usage EXAMPLES of commands and it's options, you'll find those near the end of many manpages.

Just ask here if you are unsure about something specific :)
 
Sorry, I still don't really understand what you mean.
Do you think the SYNOPSIS should explain in more datail what that programm/tool is about or how it is options should be used?
 
In the Debian and Arch Linux manpage for man (man man) there is a part in the section "DESCRIPTION" that explains how to interprete square brackets, pipe characters, bold text and italic text within the SYNOPSIS section.

See:
Code: 
The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections.

bold text type exactly as shown.
italic text replace with appropriate argument.
[-abc] any or all arguments within [ ] are optional.
-a|-b options delimited by | cannot be used together.
argument ... argument is repeatable.
[expression] ... entire expression within [ ] is repeatable.

Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead.

The command or function illustration is a pattern that should match all possible invocations. In some cases it is advisable to illustrate several exclusive invocations as is shown in the SYNOPSIS section of this manual page.

https://manpages.debian.org/jessie/man-db/man.1.en.html

I think this should also be included in the BSD manpage.
 
Ok, got it.

That is without a doubt a really a nice explanation in the SYNOPSIS section on Debian, but that won't work on FreeBSD.

Debian, as Linux in general (mostly), come as a complete distribution. Everything is put together as one preconfigured big thing and fits together. Text consol and terminal emulators in the desktop environment usually share the same terminal characteristics.

Where on FreeBSD you start with a unconfigured text console and nothing else. If you install the DE you like or just put together what you like to on Xorg, you won't get that. Terminal emulators are different from one another and all 3rd party software comes unconfigured (how it's released by the developer(s).

So chances are big that you look at a manual page on the text console or a terminal emulator and 'bold' is not available but is shown as 'highlighted and 'underlined' or 'italic' isn't available at all.
 
No, he is not joking. Unix is designed to work on many types of text terminals. That means it has to work correctly in an environment where bold, underline, italics, reverse, and colors are not available. This implies that man pages have to be written without relying on such types of text rendering.

Note what it says in the Debian man page you quoted above: "Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead." Well, that statement is technically correct, but very optimistic: on many types of terminals, neither underlined nor coloured text is available, nor bold.

Now seriously, given that today real hardware terminals have become nearly non-existing (we had a discussion about that here recently) and instead everyone uses terminal emulators, most of which run on GUIs or on VGA-style consoles. These days, the ANSI (a.k.a. VT[12]xx) command set is the de-facto standard for text-mode terminals, and one can safely assume that all terminals support bold, reverse, underline, and colors. The ANSI commands for italics exist, but are rarely supported. One could make a deliberate design choice, for example in FreeBSD (there is no longer an entity capable of controlling all Unix, that market is now fragmented) that all terminals must have those capabilities, and then change all programs that output text to use those capabilities. Such a decision would require a heck of a lot of discussion, and would take accessibility into account: color blindness, whether italics looks "different enough" form regular, and so on.

It seems that Debian has made that decision, at least for man pages. Well, good for them. I wonder how consistent they have been; for example: Are error messages in compiler output now underlined bold, and warnings in italics? Probably not. Another reason for me to not use that operating system.

And if you want to claim that "everyone" uses Unix machines with a GUI, that's just nonsense. As an example, I use somewhere between a dozen and two dozen Unix machines regularly (about 1/3 personally, the rest for work), and only one of them has a GUI attached; all others are accessed via text mode (ssh sessions).
 
There's confusion in the making here I think.

The OP is not necessarily referring to italics, colors, etc. All he's basically asking is "where does FreeBSD explain its command notation" (I have to admit that I also didn't get that at first).

Let's for example look at man(1):

Code: 
SYNOPSIS
     man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]
         [-m arch[:machine]] [-p [eprtv]] [mansect] page ...
     man -f keyword ...
     man -k keyword ...
How can you tell that [-t | -w] means: "You can optionally use either -t or -w". That's basically the OP's question if I'm not mistaken.

Well, you usually do that by reading the rest of the manualpage, though I have to admit that a small explanation section regarding the notation wouldn't hurt.
 
You must log in or register to reply here.
Back
Top