Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FLOSS] unify spelling of manpages #4567

Closed
markus2330 opened this issue Oct 18, 2022 · 8 comments · Fixed by #4692
Closed

[FLOSS] unify spelling of manpages #4567

markus2330 opened this issue Oct 18, 2022 · 8 comments · Fixed by #4692

Comments

@markus2330
Copy link
Contributor

markus2330 commented Oct 18, 2022

We currently have at least 3 spellings of manpage(s):

  1. man pages
  2. manpages
  3. man-pages

Use scripts/sed to unify.

Triage is about:

  • do we have other spellings?
  • which of the options above should we use?
@markus2330 markus2330 added 1p one point triage needed Issue needs clarifications. floss2022w labels Oct 18, 2022
@stefnotch stefnotch self-assigned this Oct 18, 2022
@stefnotch stefnotch added H1 documentation lang/markdown and removed triage needed Issue needs clarifications. labels Oct 18, 2022
@stefnotch
Copy link
Contributor

I can confirm this issue.
Searching for [mM][aA][nN].{0,3}[pP][aA][gG][eE] using Visual Studio Code (which uses ripgrep under the hood) yields 260 results.
The vast majority seem to use the first spelling, that is "man pages".

So now to find different ones, we tweak the regex to not search for a space in the middle [mM][aA][nN][^ ]{0,3}[pP][aA][gG][eE]. At this point, a lot of results will be things like variables or links.
e.g.
Variables: generate_manpage, ${MANPAGE}, MAN_PAGE_LOCATION, runManPage, ...
Links: https://www.libelektra.org/manpages/kdb, https://en.wikipedia.org/wiki/Man_page, ...

Proposal
I'd propose unifying the spelling to "man page" with a separator. Although, depending on the context, a different separator can make sense. generate_manpage would thus become generate_man_page. Meanwhile something like runManPage is already fine under that proposal.

Another thing that we should take a look at is file names. There's at least one file containing the words "man page", namely ElektraManPage.cmake.

And finally, the tricky part that I'm unsure about:
How does one go about updating the https://www.libelektra.org/manpages/... links? According to the Google guidelines we could use https://www.libelektra.org/man-pages/.... At the same time, we do want to have a redirect from our old https://www.libelektra.org/manpages/... URLs to the new ones, after all, a good URL should never break.

@kodebach
Copy link
Member

Most English sources I found in a quick Google search use "man page". Both "manpage" and "man-page" seem to be more of a German thing...

@flo91
Copy link
Collaborator

flo91 commented Oct 18, 2022

Most English sources I found in a quick Google search use "man page". Both "manpage" and "man-page" seem to be more of a German thing...

Your research result squares with the proposal from @stefnotch:

I'd propose unifying the spelling to "man page" with a separator.

So normally, the separator is a space, but in many cases, spaces are not allowed, so either a CamelCase variant manPage, or other separators like - or _ must be used.

The file name ElektraManPage.cmake looks fine to me.
The man pages on the website refer to files on the GitHub respository available at https://github.com/ElektraInitiative/libelektra/tree/master/doc/help.
But you're right, if we want to change the URLs to contain man-pages instead of manpages, we should create a redirect or offer the man pages under both URLs.

@flo91 flo91 changed the title unify spelling of manpages [FLOSS] unify spelling of manpages Oct 18, 2022
@markus2330
Copy link
Contributor Author

Nice triage, thank you!

markus2330 pushed a commit to markus2330/libelektra that referenced this issue Oct 20, 2022
@stefnotch
Copy link
Contributor

We'll take a stab at this for T1

@stefnotch
Copy link
Contributor

stefnotch commented Nov 20, 2022

Categories of different spellings
bad:
Manpage
manpage
MANPAGE
manpages

good:
man_page
MAN_PAGE
manPage
Man_page

good except in some cases:
man-page (fine in URLs or file names, bad in plaintext)

More bad results can easily be found with [mM][aA][nN][^-_ ]{0,3}[pP][aA][gG][eE]

@markus2330
Copy link
Contributor Author

Man_page

Is this for file names? Otherwise you better would say "Man page" (without quotes)?

@stefnotch
Copy link
Contributor

For file names or other cases where underscore_case is the way to go.
e.g. generate_manpage would become generate_man_page

joni1993 pushed a commit to joni1993/libelektra that referenced this issue Dec 5, 2022
Janldeboer pushed a commit to Janldeboer/libelektra that referenced this issue Dec 12, 2022
Dynamichost96 pushed a commit to Dynamichost96/libelektra that referenced this issue Jan 15, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants