Update man page + change `[FILE]:LINE:COL` to `FILE[:LINE:COL]` in `micro -help` by dmaluka · Pull Request #3812 · micro-editor/micro

dmaluka · 2025-07-20T23:14:52Z

Update micro's man page (which hasn't been updated since 2020): align it with micro -help
Change confusing [FILE]:LINE:COL to FILE[:LINE:COL] in micro -help (and in the man page, obviously)

cutelisp · 2025-07-21T00:39:22Z

assets/packaging/micro.1

@@ -95,9 +109,14 @@ file (see 'help options').
 .PP
 \-option value


I think -option is tricky. (I've been tricked by this in the past)
Could we change it so it's clear that's a variable? e.g. -<option>

Could we change it so it's clear that's a variable? e.g. -

Looks like your comment got cut off?

How about -<option>?

Yep, -<option> is better.
To be changed for the command options too.

Actually man man says this

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.

They suggest using italic for argument, I like <> tho.
We should use it on -config-dir dir as well (-config-dir <dir> )?

bold text type exactly as shown.

Every man page I looked into respects this notation with flags, so we probably use it as well.

micro [OPTIONS] [FILE]...

This isn't always true, since if OPTION is, for example,-version or -plugin list FILE is not a valid argument anymore since micro won't open.
Multiple options can be passed so [OPTIONS]...?

Suggestion:
Split current options into options/commands (on options section).

Synopsis
micro [OPTIONS]... [FILE]...
micro [OPTIONS]... FILE[:LINE[:COL]]...
micro [COMMAND]

They suggest using italic for argument, I like <> tho.
We should use it on -config-dir dir as well (-config-dir <dir> )?

[...]

Every man page I looked into respects this notation with flags, so we probably use it as well.

We could. OTOH man vim, for instance, does it plain, without italic or bold or <>. No one seems to be dying because of that.

Multiple options can be passed so [OPTIONS]...?

OPTIONS is already plural. Also man vim, for instance, has vim [options] [file ..]

But I'm ok with changing it to [OPTION]... (singular).

Also let's not forget about the +LINE:COL syntax (which, unlike :LINE:COL, works always, not only if parsecursor is enabled; OTOH, unlike :LINE:COL, it works for a single file on the command line only).

So, this?

micro [OPTION]... [FILE]... micro [OPTION]... [FILE[:LINE[:COL]]]... (only if the `parsecursor` option is enabled) micro [OPTION]... FILE +LINE[:COL]

This isn't always true, since if OPTION is, for example,-version or -plugin list FILE is not a valid argument anymore since micro won't open.

[...]

micro [COMMAND]

I see more problems than advantages with that. That would mean that we, for purely formalistic reasons, are introducing a concept of "command" as a special case of an "option". Whereas we already, for instance, use the term "command" to refer to plugin commands selected by the -plugin flag: install, remove etc.

We could instead just add "...and exit" to the descriptions of those options: -clean: "Clean the configuration directory and exit", -options: "Show all option help and exit" and so on.

I'd like to prevent us all from this duplicated maintenance effort and risk of async documentation.

That is not exactly a huge effort, is it?

And if we forget to update the man page once again, we will recall again after another 5 years.

(OTOH, if there are multiple +LINE[:COL]] params, only the last one is applied (to all files), all the previous ones are ignored.)

It's reasonable ig, since +LINE[:COL]] it's meant to be used once.

Also, BTW, LINE:COL and +LINE:COL are mutually exclusive (and +LINE:COL takes priority), i.e. micro foo:10 bar +20 will not open foo at line 10 and bar at line 20, it will open foo:10 and bar, both at line 20. So, we will not be lying when we put micro [OPTION]... [FILE]... +LINE[:COL] at a separate line in the man page.

If they are mutually exclusive why not as I suggested?

micro [OPTION]... [FILE]... [+LINE[:COL]] micro [OPTION]... [FILE[:LINE[:COL]]]... (only if the `parsecursor` option is enabled)

If they are mutually exclusive why not as I suggested?

micro [OPTION]... [FILE]... [+LINE[:COL]] micro [OPTION]... [FILE[:LINE[:COL]]]... (only if the `parsecursor` option is enabled)

Well, yeah, makes sense. (Haven't noticed your suggestion first time.)

I hope this high density of brackets won't scare anyone off.

And if we forget to update the man page once again, we will recall again after another 5 years.

Please add at least a comment somewhere around...
https://github.com/zyedidia/micro/blob/d7e43d497448cc30a20c38b8d76388877f6918e7/cmd/micro/micro.go#L49
...to // keep in sync with the man page located in assets/packaging/micro.1.

Pushed updated version. I also ended up improving man page formatting as well, to use bold and italic as man man recommends.

cutelisp · 2025-07-21T00:45:47Z

FILE[:LINE:COL] -> COL is not mandatory so it should be FILE[:LINE[:COL]]?

I think something like micro [OPTIONS] [FILE[:LINE[:COL]]]... (if the parsecursor option is enabled) could be added to synopsis.

cutelisp · 2025-07-21T01:27:37Z

assets/packaging/micro.1


 .PP
-[FILE]:LINE:COL
+FILE[:LINE:COL] (if the `parsecursor` option is enabled)


I took a look at gedit man page I think it would be better to do something similar.

My suggestion is to swap this by something like this (under -version):

FILE Specifies the file to open when micro starts. If no files are passed, micro starts with an empty buffer. FILE[:LINE[:COL]] If the `parsecursor` option is enabled, a line number can be specified to position the cursor when opening a file. Optionally, a column number can also be provided to set the cursor position within that line.

At least in the command options fmt.Println("Usage: micro [OPTIONS] [FILE]...") already stands for its own. At least there we don't need the dedicated [FILE] description.

I agree regarding FILE[:LINE[:COL]], since [:COL] is optional.

JoeKar

However, the fact that we have to maintain it in two different places is disturbing.
This makes it easier to forget to update one of them.

JoeKar · 2025-07-21T16:52:37Z

assets/packaging/micro.1

@@ -95,9 +109,14 @@ file (see 'help options').
 .PP
 \-option value


Yep, -<option> is better.
To be changed for the command options too.

JoeKar · 2025-07-21T16:54:09Z

assets/packaging/micro.1


 .PP
-[FILE]:LINE:COL
+FILE[:LINE:COL] (if the `parsecursor` option is enabled)


At least in the command options fmt.Println("Usage: micro [OPTIONS] [FILE]...") already stands for its own. At least there we don't need the dedicated [FILE] description.

I agree regarding FILE[:LINE[:COL]], since [:COL] is optional.

niten94 · 2025-07-23T09:50:02Z

The last modification date of the man page at line 1 may have to be updated, like noted in man-pages(7) (Linux man-pages project):
https://github.com/zyedidia/micro/blob/d7e43d497448cc30a20c38b8d76388877f6918e7/assets/packaging/micro.1#L1

I suggest to also remove blank lines in this pull request, since they seem to be unnecessary and only hidden with man-db which is used in most Linux distributions.

The empty lines cause extra space to be displayed with other man implementations, like mandoc (default in OpenBSD, Alpine Linux and Termux) and the one in FreeBSD. To test on Debian for example, mandoc's implementation is named mman and included in the mandoc package.

dmaluka · 2025-08-16T14:46:51Z

The empty lines cause extra space to be displayed with other man implementations, like mandoc (default in OpenBSD, Alpine Linux and Termux) and the one in FreeBSD. To test on Debian for example, mandoc's implementation is named mman and included in the mandoc package.

Thanks for pointing this out. Done.

assets/packaging/micro.1

JoeKar · 2025-08-18T17:33:06Z

assets/packaging/micro.1

+.B micro
+.RI [ OPTION ]...\&
+.RI [ FILE [: LINE [: COL ]]]...\&
+\& (only if the `parsecursor` option is enabled)")


The ") or )" is a c&p issue from...

fmt.Println("FILE:LINE[:COL] (only if the `parsecursor` option is enabled)")

...right¹? 😉

Footnotes

Preview checked with https://roperzh.github.io/grapse/. ↩

Yeah right, thanks.

Preview checked with https://roperzh.github.io/grapse/.

FWIW it can be checked simply with man ./assets/packaging/micro.1

Align it with `micro -help`.

Display option names in bold text and argument placeholders in italic text, as recommended in `man man`.

@niten94

As pointed out by @niten94, empty lines in the man page are not just unnecessary but also cause extra empty lines to be displayed with alternative `man` implementations, e.g. `mandoc`. To test on Debian, for example, mandoc's implementation is named `mman` and included in the `mandoc` package.

niten94 · 2025-08-22T14:28:09Z

Unlikely other people would look at the PR comments now, but small clarification on my statement:

To test on Debian for example, mandoc's implementation is named mman and included in the mandoc package.

Mandoc can be ran in the same way as the man-db implementation to view a file.

The mandoc package provided by other distributions conflict with man-db due to the same executable name of man, but it should be possible to download the package, extract anywhere and run due to minimal dependencies.

dmaluka force-pushed the update-manpage branch from f84657a to f5725a6 Compare July 20, 2025 23:26

dmaluka mentioned this pull request Jul 20, 2025

[FILE]:LINE:COL construct fails to display file #3811

Closed

cutelisp reviewed Jul 21, 2025

View reviewed changes

JoeKar reviewed Jul 21, 2025

View reviewed changes

dmaluka force-pushed the update-manpage branch from f5725a6 to 8d0f6f3 Compare August 16, 2025 14:20

Improve micro -help output

f735ff0

dmaluka force-pushed the update-manpage branch from 8d0f6f3 to 119790f Compare August 16, 2025 14:47

JoeKar reviewed Aug 17, 2025

View reviewed changes

assets/packaging/micro.1 Show resolved Hide resolved

JoeKar reviewed Aug 18, 2025

View reviewed changes

dmaluka added 3 commits August 19, 2025 01:55

Update man page

20ebca9

Align it with `micro -help`.

man page: Improve formatting

2b5eb3e

Display option names in bold text and argument placeholders in italic text, as recommended in `man man`.

dmaluka force-pushed the update-manpage branch from 119790f to c7d65d1 Compare August 18, 2025 23:59

JoeKar approved these changes Aug 19, 2025

View reviewed changes

JoeKar merged commit 421da67 into micro-editor:master Aug 19, 2025
6 checks passed

dmaluka mentioned this pull request Sep 3, 2025

micro: Handle +/text search text from args #3767

Merged

		@@ -95,9 +109,14 @@ file (see 'help options').
		.PP
		\-option value

Conversation

dmaluka commented Jul 20, 2025

Uh oh!

cutelisp Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmaluka Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cutelisp commented Jul 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoeKar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

niten94 commented Jul 23, 2025

Uh oh!

dmaluka commented Aug 16, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

niten94 commented Aug 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cutelisp Jul 21, 2025 •

edited

Loading

dmaluka Jul 22, 2025 •

edited

Loading