search

johnmehr / gitup

A minimalist, dependency-free FreeBSD program to clone/pull Git repositories.
BSD 2-Clause "Simplified" License
50 stars 9 forks source link

The installed manual page does not show a section #57

Closed grahamperrin closed 3 years ago

grahamperrin commented 3 years ago 
GITUP                                LOCAL                               GITUP

NAME
     gitup – A minimalist, dependency-free program to clone/pull Git
     repositories.

SYNOPSIS
     gitup section [-ckrV] [-C configuration file] [-h commit checksum]
           [-t tag] [-u pack file] [-v verbosity] [-w commit checksum]

DESCRIPTION
…

man 1 gitup works where (for example) man 8 gitup does not, so I guess that this is a cosmetic issue.

johnmehr commented 3 years ago

Do you think it's more appropriate for the man page to exist in section 8 or should it exist in both section 1 and section 8? Thank you!

grahamperrin commented 3 years ago

I'm no expert, but I assume that it's impossible (or undesirable) to have a single manual page appear in more than one section.

https://man.freebsd.org/man(1)

I see 1 in the file name of https://github.com/johnmehr/gitup/blob/main/gitup.1.in but I wonder whether section 8 will be more appropriate. Food for thought: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=254466#c2

Through answers to https://unix.stackexchange.com/q/3586/13260 I'm reminded of:

From the intro to section 8:

… A number of pages in this section describe general system management topics. …

Hope that helps. If in doubt about which section to choose, maybe seek guidance from freebsd-hackers https://lists.freebsd.org/mailman/listinfo/freebsd-hackers – the primary technical mailing list. Do you subscribe?

michael-o commented 3 years ago

I don't think that section 8 is appropriate because gitup can be used as a lightweight alternative to git(1). It does not necessarily require admin permissions.

grahamperrin commented 3 years ago

Thanks, on the other hand: /usr/ports/ and /usr/src/ are drwxr-xr-x … root wheel by default with a fresh installation of FreeBSD, so the most common use cases will be superuser.

Unless I'm missing something, work with ports and src is nearly always with system management in mind.

michael-o commented 3 years ago

That's correct, but gitup hasn't been explicitly written for that. Ultimately it depends on the conf file whether an admin or a regular user uses this.

johnmehr commented 3 years ago

I can see it going in either section but I think the point that @michael-o makes is persuasive here. Thank you for raising the issue!

grahamperrin commented 3 years ago

Sorry, am I missing something? Will there be a commit for the page to show a section?

johnmehr commented 3 years ago

I think the fault is on my end -- I'm not following you. Could you please elaborate on what you'd like to see? Thanks.

grahamperrin commented 3 years ago

Compare with the window in the background: there's no number in parentheses.

image