Add man page for Unix-like systems

[sorairolake]

Microsoft Edit is a command-line text editor primarily for Windows, but also works on Unix-like systems such as Linux. Other command-line text editors which run on Unix-like systems, such as emacs, micro, nano, or vim, come with a man page. I don't think that Unix-like systems are the primary target of Microsoft Edit, but it would be better to have a man page for these systems, because this is a command-line text editor which run on these systems too.

[elsaco]

Before adding a separate man page on a Linux system, which would complicate packaging, edit could benefit from a help file that would document usage, options, etc.

On Linux, pressing F1 or Ctrl-G while using nano shows the Main nano help text in the editor.

[rhubarb-geek-nz]

A man page in each supported language, of course.

[schilive]

The original EDIT did have an interactive help menu. So did other MS-DOS programs like Turbo C IDE and DOSSHELL. A more modern-looking solution may be something that looks more like website-y or HTML-y, maybe similar to GNU Info.

[sorairolake]

If maintainability is important, I think a man page would be better written in a lightweight markup language such as AsciiDoc, Markdown, or reStructuredText. This has the disadvantage that a converter such as Asciidoctor or Pandoc is required to convert the man page to troff. So if the man page is written once and will not be changed much afterwards, it may be better to write the man page directly in troff.

[rhubarb-geek-nz]

I really don't see the need for integrated help in an app these days. Back in MS-DOS where you could only have one program open at a time it was the best thing to do. In all honesty it would be far better to simply have a website that tells you what you need to know. But the app should be so simple and the menus so clear that that there should be very little explaining to do. A man page, if provided, should be accessed using the man tool.

.TH EDIT 1 "version 1.0" "May 2025"
.SH NAME
edit \- a simple text editor
.SH SYNOPSIS
edit [file]
.SH DESCRIPTION
edit is a simple text editor inspired by MS-DOS edit.
.SH EDITING
Edit is an interactive mode-less editor.
.SH OPTIONS
Pass the name of the file to edit.
.SH SEE ALSO
https://github.com/microsoft/edit
.SH AUTHOR
Leonard Hecker

Is all you need.

$ nroff -man < edit.1
EDIT(1)                     General Commands Manual                    EDIT(1)



NAME
       edit - a simple text editor

SYNOPSIS
       edit [file]

DESCRIPTION
       edit is a simple text editor inspired by MS-DOS edit.

EDITING
       Edit is an interactive mode-less editor.

OPTIONS
       Pass the name of the file to edit.

SEE ALSO
       https://github.com/microsoft/edit

AUTHOR
       Leonard Hecker



May 2025                          version 1.0                          EDIT(1)

[rhubarb-geek-nz]

The help for MS-DOS is already complete, and integrated with the main help system....

C:\>help edit
This command is not supported by the help utility.  Try "edit /?".

C:\>edit /?
Usage: edit [OPTIONS] [FILE]
Options:
    -h, --help       Print this help message
    -v, --version    Print the version number

What more needs to be said?

[schilive]

I disagree that there should be "little explaining to do". I want it to be simple, but if a simple shortcut, like "moving a line", is added, then what keys it uses may not be obvious. And I think a man page would be great, but I am not sure Windows can handle them with ease, and this is mainly a Windows app. At the same time, both in MS-DOS and modernly, many programs have no manual in the computer, only on-line or similar. So, I guess it should be within what is expected, to have no manual, either integrated or through a man page..

However, I love good integrated manuals, since I can just look up what to do. For example, I think BRIEF had some interesting ideas. When you used ALT + H, a help menu would pop-up. This seems rather inconvenient, but the options could be selected by simply pressing a letter. So, for example, if I wanted see the menu for the summary of all shortcuts, I would just press ALT + H, Q. Or something like this. I think this is both good for 1) unexperienced users who want to explore the editor, and 2) experienced people who just wanna find that thing. In comparison, I think Vim's help menu is good for learning the details of something, but horrible for look-up and learning. However, something I did like of Vim and miss in BRIEF, was looking up things by words.

Anyway, the good thing of adding this feature is that people who don't like it, won't mind it. The problem is the HOW. I mean, the text shouldn't take up too much space if done "well". Another idea is to simply not add this by default, but have it as a plug-in that people can add. Or have a simplified version and a plug-in can make it complex.

[rhubarb-geek-nz]

but if a simple shortcut, like "moving a line", is added, then what keys it uses may not be obvious.

Then the short cut should not have been added in the first place. Everything should be discoverable by looking through the menus and either selecting the menu option directly or using the short cut listed next to the menu.

There should be no magic key presses.

"Moving a line" should not exist, the mechanism should be "Cut" then "Paste" as it has been for 30 years. This is not a line editor, the public consensus was not to implement edlin.

To be honest, nobody is going to read the man page, except to say "cute, it has a man page". If you have to use the man page it has failed as a usable editor.

A man page is not a plug-in, it is a resource that is used when creating RPM, Debian or similar packages. The program is completely unaware of it. The installation then puts it in /usr/share/man/man1, and that is the end of the story.

[sorairolake]

This was solved by #263.