Bug 84956 - intro(5) manpage doesn't mention API coverage
Summary: intro(5) manpage doesn't mention API coverage
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Some People
Assignee: freebsd-bugs (Nobody)
URL: https://www.freebsd.org/cgi/man.cgi?q...
Keywords: needs-qa, patch
Depends on:
Blocks: 248562
  Show dependency treegraph
 
Reported: 2005-08-15 16:40 UTC by Gary W. Swearingen
Modified: 2022-10-17 15:25 UTC (History)
2 users (show)

See Also:


Attachments
file.diff (474 bytes, patch)
2005-08-15 16:40 UTC, Gary W. Swearingen
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Gary W. Swearingen 2005-08-15 16:40:09 UTC
The intro(5) manpage doesn't mention that some APIs are
documented in section 5 too.  E.g., link(5) & acct(5)

It also has an seemingly-extraneous reference to intro(8).

How-To-Repeat: n/a
Comment 1 Giorgos Keramidas freebsd_committer freebsd_triage 2005-08-16 16:56:40 UTC
On 2005-08-15 08:38, "Gary W. Swearingen" <garys@opusnet.com> wrote:
> The intro(5) manpage doesn't mention that some APIs are
> documented in section 5 too.  E.g., link(5) & acct(5)

Ouch!  The link(5) and acct(5) manpages seem a bit misplaced.  They
don't describe a "file format", so they shouldn't be in section (5)
IMHO.  There are a few other manpages in ``/usr/share/man/man5''
that I am not sure about either.

> --- intro..orig.5	Sun Aug  7 21:58:11 2005
> +++ intro.5	Sun Aug  7 22:07:22 2005
> @@ -38,11 +38,11 @@
>  .Nm intro
>  .Nd "introduction to file formats"
>  .Sh DESCRIPTION
> -This section contains information about file formats.
> +This section contains information about file formats
> +and some system Application Programming Interfaces (API .h files).
>  .Sh SEE ALSO
>  .Xr apropos 1 ,
> -.Xr intro 1 ,
> -.Xr intro 8
> +.Xr intro 1

My intuition says that anyone who is reading intro(X) manpages should be
able to find out about all the other intro(Y) manpages.  So, it seems
that inter-linking from any intro(X) manpage to the other intro(Y)
manpages, where X != Y, seems reasonable.

- Giorgos
Comment 2 Gary W. Swearingen 2005-08-16 20:09:19 UTC
Giorgos Keramidas <keramida@freebsd.org> writes:

> Ouch!  The link(5) and acct(5) manpages seem a bit misplaced.  They
> don't describe a "file format", so they shouldn't be in section (5)
> IMHO.  There are a few other manpages in ``/usr/share/man/man5''
> that I am not sure about either.

If you want me to do something, let me know.  I could do more research
and maybe ask ask on one or more lists whether people have objections
to moving each seemingly-misplaced manpage to a newly-proposed section.

> My intuition says that anyone who is reading intro(X) manpages should be
> able to find out about all the other intro(Y) manpages.  So, it seems
> that inter-linking from any intro(X) manpage to the other intro(Y)
> manpages, where X != Y, seems reasonable.

Are you saying they should each reference all the others?  OK by me,
but I think it would better to have them all reference only intro(1),
which already references all the others (except "intro(n)" because it
does not exist). Manpage intro(1) probably also should have a section
explaining the manual in general. I'll write PRs on the last two
problems.

But intro(5) should not reference only intro(1) and intro(8).
Comment 3 Giorgos Keramidas freebsd_committer freebsd_triage 2005-08-16 20:25:16 UTC
On 2005-08-16 12:09, "Gary W. Swearingen" <garys@opusnet.com> wrote:
> Giorgos Keramidas <keramida@freebsd.org> writes:
> 
> > Ouch!  The link(5) and acct(5) manpages seem a bit misplaced.  They
> > don't describe a "file format", so they shouldn't be in section (5)
> > IMHO.  There are a few other manpages in ``/usr/share/man/man5''
> > that I am not sure about either.
> 
> If you want me to do something, let me know.  I could do more research
> and maybe ask ask on one or more lists whether people have objections
> to moving each seemingly-misplaced manpage to a newly-proposed section.
> 
> > My intuition says that anyone who is reading intro(X) manpages should be
> > able to find out about all the other intro(Y) manpages.  So, it seems
> > that inter-linking from any intro(X) manpage to the other intro(Y)
> > manpages, where X != Y, seems reasonable.
> 
> Are you saying they should each reference all the others?

Exactly.

> OK by me, but I think it would better to have them all reference only
> intro(1), which already references all the others (except "intro(n)"
> because it does not exist).

I guess that's ok too.  I opted for the first option (of adding SEE ALSO
entries for all the intro(x) manpages) because when a reader sees a
reference to intro(1) in one of the others it's not entirely obvious
that there also exist intro(2), intro(3), etc. manpages.  Saving one
level of indirection, by pointing to all the intro(x) manpages from all
the rest, makes it more obvious that there exist manpage ``sections''
and that they are those linked from SEE ALSO.

I'm ok with just pointing to intro(1) too though.  As long as it's
consistent (i.e. done in all the intro(x) manpages, like you proposed).

> Manpage intro(1) probably also should have a section explaining the
> manual in general. I'll write PRs on the last two problems.

Good idea.  It always made me feel a bit weird that to find a list of
all the manpage sections I should go to groff_mdoc(7) and scroll several
pages down.

> But intro(5) should not reference only intro(1) and intro(8).

Sounds reasonable.

Thanks,
Giorgos
Comment 4 Gary W. Swearingen 2005-08-16 22:15:10 UTC
Let's drop the intro(8) problem from this PR, leaving the subject
problem.

I'll write another PR for expanding all the "SEE ALSO"s.  (I'll credit
you for the idea. I'm not sure how popular it will be, for example,
in intro(4). :)

Please let me know if you want the multiple patches in the PR or not.
I don't know if you'd rather just edit the files than apply patches
and check the results.
Comment 5 Giorgos Keramidas freebsd_committer freebsd_triage 2005-08-16 22:44:49 UTC
On 2005-08-15 08:38, "Gary W. Swearingen" <garys@opusnet.com> wrote:
> --- intro..orig.5	Sun Aug  7 21:58:11 2005
> +++ intro.5	Sun Aug  7 22:07:22 2005
> @@ -38,11 +38,11 @@
>  .Nm intro
>  .Nd "introduction to file formats"
>  .Sh DESCRIPTION
> -This section contains information about file formats.
> +This section contains information about file formats
> +and some system Application Programming Interfaces (API .h files).
>  .Sh SEE ALSO
>  .Xr apropos 1 ,
> -.Xr intro 1 ,
> -.Xr intro 8
> +.Xr intro 1
>  .Sh FILES
>  .Bl -tag -width /etc/shells -compact
>  .It Pa /etc

I've been trying to find a good way to write down the same information
without the inline parentheses and the need to quote ".h" with something
like:

	.Dq Li \&.h

Does this look ok to you Gary?  I've removed the reference to ".h" files
only because people who know enough about C already don't need to know
this and people who don't know enough about C aren't (usually)
interested in what the specific meaning of "API .h files" is.

Here's the diff:

% Index: intro.5
% ===================================================================
% RCS file: /home/ncvs/src/share/man/man5/intro.5,v
% retrieving revision 1.7
% diff -u -r1.7 intro.5
% --- intro.5	21 Jan 2005 08:36:39 -0000	1.7
% +++ intro.5	16 Aug 2005 21:39:15 -0000
% @@ -38,7 +38,10 @@
%  .Nm intro
%  .Nd "introduction to file formats"
%  .Sh DESCRIPTION
% -This section contains information about file formats.
% +This section contains information about file formats and some system
% +Application Programming Interface
% +.Pq API
% +files.
%  .Sh FILES
%  .Bl -tag -width /etc/shells -compact
%  .It Pa /etc

If this looks ok to you, I'll commit it.  Otherwise, I'll have to let
other, more mdoc-savvy people handle this.

- Giorgos
Comment 6 Gary W. Swearingen 2005-08-17 01:40:01 UTC
Giorgos Keramidas <keramida@freebsd.org> writes:

> I've been trying to find a good way to write down the same information
> without the inline parentheses and the need to quote ".h" with something
> like:
>
> 	.Dq Li \&.h

Why use "\&"?  It's unneeded, AFAICT.  Are single-character macros
even allowed?

"Pa" ("Path") might be more appropriate than "Li" and removes the need
for "Dq".

I assume that your use of a macro for ".h" necessitates a macro for
parentheses; if there's a general problem with in-line parentheses,
please let me know.

> Does this look ok to you Gary?  I've removed the reference to ".h" files
> only because people who know enough about C already don't need to know
> this and people who don't know enough about C aren't (usually)
> interested in what the specific meaning of "API .h files" is.

First off, I'm wondering why you want to change the manpage at all,
since I thought that you didn't want the API/.h manpages in the
section.  Without thinking much about link(5), acct(5), and others, I
thought that you were probably right and the intro(5) manpage didn't
need to be changed because the others would be moved out of the
section.  But maybe you've come to the same conclusion I now have,
after thinking more about link(5) and acct(5): that there is no better
place for them.  Furthermore, in a way, they are manpages for .h "file
formats", if you stretch the meaning.  Note that these .h files have
no direct affiliation with programs or libraries or other things
covered by other manual sections.

So while I prefer some change to the manpage (only if acct(5), etc,
are not moving), I'm OK if you'd rather not change it at all.

As for my parenthetical phrase, you're right: readers probably only
need to know that the section also covers XXX, where the meaning of
"XXX" (.h files) doesn't matter as long as it obviously means
something other than "file formats".  So I would recommend something
like this:

+This section contains information about file formats
+and about a few
+.Pa .h
+files not appropriate for other manual sections.

(I repeated "about" to avoid an ambiguous meaning.)
Comment 7 Giorgos Keramidas 2005-08-17 13:24:53 UTC
On 2005-08-16 17:40, "Gary W. Swearingen" <garys@opusnet.com> wrote:
>Giorgos Keramidas <keramida@freebsd.org> writes:
>> I've been trying to find a good way to write down the same information
>> without the inline parentheses and the need to quote ".h" with something
>> like:
>>
>> 	.Dq Li \&.h
>
> Why use "\&"?  It's unneeded, AFAICT.  Are single-character macros
> even allowed?

I'm not guarding only against groff expanding .h as a macro.  groff may
automatically choose to break inline text whenever a punctuation mark
appears or insert whitespace before, after or even both before and after
such characters.  This is why I used \& to protect the space before the
dot.

> "Pa" ("Path") might be more appropriate than "Li" and removes the need
> for "Dq".

It's not a path name though.  It's a filename extension that is quoted
literally as part of the running text.  I prefer to use .Pa for complete
filenames (like ``.Pa fstab'') or for path names with more components
(like ``../foo'' or ``/etc/ttys'').

> I assume that your use of a macro for ".h" necessitates a macro for
> parentheses; if there's a general problem with in-line parentheses,
> please let me know.

Not really.  I'm not sure if inline parentheses are preferred over more
explicit markup.  I tend to prefer the style of the left column shown
below, but the definitive source for making an informed decision on this
matter is Ruslan:


	GOOD STYLE		BAD STYLE		OUTPUT

	.Pq bar			(bar)			(bar)

	.Po			(This text is		(This text is
	This text is		parenthesized).		parenthesized).
	parenthesized
	.Pc .

The extra markup is not only a matter of "having the right output
format", but it's also (ala SGML) a matter of making the structure of
the text apparent.

> First off, I'm wondering why you want to change the manpage at all,
> since I thought that you didn't want the API/.h manpages in the
> section.

Because its description section is incomplete right now.  When we get
approval from CVS meisters about a repo-move of the manpages to other
sections and *if* we do get an approval for moving all of them, then
the extra text can be removed.

> Without thinking much about link(5), acct(5), and others, I thought
> that you were probably right and the intro(5) manpage didn't need to
> be changed because the others would be moved out of the section.

This may take some time.

> But maybe you've come to the same conclusion I now have, after
> thinking more about link(5) and acct(5): that there is no better place
> for them.

It did cross my mind.  So you think we have no good place for them, and
the change should be done to intro(5)?

> Furthermore, in a way, they are manpages for .h "file formats", if you
> stretch the meaning.  Note that these .h files have no direct
> affiliation with programs or libraries or other things covered by
> other manual sections.

More or less.  I've began thinking think they were put in section 5
because ``there isn't a section that may match their intent better
than section 5 right now''.

> So while I prefer some change to the manpage (only if acct(5), etc,
> are not moving), I'm OK if you'd rather not change it at all.

I'll make the change.  The other manpages may take a long time to be
moved into a more appropriate section, or they may never get moved at
all.  Fixing the description right now instead of waiting for what may
never happen is better :)

> +This section contains information about file formats
> +and about a few
> +.Pa .h
> +files not appropriate for other manual sections.
>
> (I repeated "about" to avoid an ambiguous meaning.)
Comment 8 Gary W. Swearingen 2005-08-17 15:34:27 UTC
Giorgos Keramidas <keramida@ceid.upatras.gr> writes:

> such characters.  This is why I used \& to protect the space before the
> dot.

You wanted "``.h''", so there is no space.  But I can believe it is
sometimes needed and maybe should be a habit within macros.

> The extra markup is not only a matter of "having the right output
> format", but it's also (ala SGML) a matter of making the structure of
> the text apparent.

The structure of "(something)" is more apparent than ".Pq something",
IMO.  BTW, the mdoc(7) source is loaded with in-line parens.

> It did cross my mind.  So you think we have no good place for them, and
> the change should be done to intro(5)?

If moving was fast and easy, I'd probably move them to section 7, but
it's not, so yes.
Comment 9 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 07:58:25 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped
Comment 10 Graham Perrin freebsd_committer freebsd_triage 2022-10-17 12:34:09 UTC
Keyword: 

    patch
or  patch-ready

– in lieu of summary line prefix: 

    [patch]

* bulk change for the keyword
* summary lines may be edited manually (not in bulk). 

Keyword descriptions and search interface: 

    <https://bugs.freebsd.org/bugzilla/describekeywords.cgi>
Comment 11 Graham Perrin freebsd_committer freebsd_triage 2022-10-17 13:37:41 UTC
(In reply to Gary W. Swearingen from comment #4)

> … I'll write another PR for expanding all the "SEE ALSO"s.  (I'll 
> credit you for the idea. I'm not sure how popular it will be, 
> for example, in intro(4). :) …

I am entirely certain that it will be no less popular, tomorrow, than it would have been when the idea was shared seventeen years ago. 

To Gary, and to any of his FreeBSD-loving descendants who may have been born during the era: 

* permission to proceed.