dotnet / dotnet/command-line-api

Support opening a web page for extensive help

Offen
#494 2 Kommentare 4 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Area-Documentation Area-Help enhancement
Vorherrschende Sprache
C#
Sterne
3.7k
Forks
428
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

Issue #400 asks for allowing users to write examples, but I think that might be asking too much of what's available from the command line. It's nice to have all your help in one spot, but practically speaking, it adds some baggage. For example, if all the documentation is compiled into the project itself, if somebody wants to contribute better help, it has be be pull-requested into the project, built, released and deployed. That's not to mention that command windows aren't really optimized for presenting multiple pages of text.

There are several systems that support a different model, where there's a way to bring up a web page from the command line. Let's take a familiar example: 'git checkout --help' brings up extensive help for checkout in your web browser. As the git example shows, it's a popular idea, but there's not a clearly preferred way to do it: 'git' actually implements this idea in two ways because there's also 'git help checkout' which is the same as 'git checkout --help'. Given this, it'll surprise noone that 'git help checkout' takes you to a web page but 'git help' does not.

So if there's a clear and consistent way to implement this thing, git hasn't discovered it. Perhaps somebody else can point to a more successful example?

For our team, we're fond of the name '--wiki' because that's where we house our documentation. Our reasoning is simply that our tools are released to a limited audience, so we're happy to have anybody contribute back better help and have it get shared immediately, rather than having to wait for a release cycle to bring forth the goodness.

Thoughts?

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit der Überprüfung der vorhandenen Einstiegspunkte für die Befehlszeilenhilfe und vergleiche das Verhalten von `git checkout --help` und `git help checkout`. Lege eine konsistente Option wie `--wiki` fest, einschließlich der Zuordnung zur Web-Dokumentation und dessen, was für den grundlegenden `git help`-ähnlichen Befehl geschehen soll.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
csharp, git
Bereich
cli, documentation
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.