Finish the manual and help pages for the first usable release

Aperta
  • Qualcosa non va?
#125 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
70/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
bash, markdown, powershell
Ambito
documentation

Direzione di ricerca

Start by reading docs/manual/labyrinth.md and the help text in labyrinth.sh and labyrinth.ps1 to map missing pages. Run tools/manual/build.sh to build the man page and PDFs, and tests/manual/manual.bats to see current gaps. Done means laby -h lists every action with its own page, each module has an about.txt under 78 columns, and the Manuals CI job builds without warnings.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

area: command-line platform: linux platform: windows type: docs

Location & Context

The operator's built-in help, as the first usable release ships it:

  • The manual: docs/manual/labyrinth.md, built by tools/manual/build.sh into the man page (man laby), the Windows help topic (Get-Help about_Labyrinth) and the PDFs, and opened by laby --manual (#65).
  • The help text in labyrinth.sh and labyrinth.ps1: laby --help / laby -h, and each action's own page, such as laby -h undo.
  • Each module's about.txt, shown by laby -h MODULE (#121; design 00, section 4).
  • Checks: tests/manual/manual.bats and the runners' help tests.

Current Behavior

Each branch adds its own command, option and exit code to the manual, and manual.bats checks that each platform's manual lists them. Nothing checks the help as a whole once the release's commands are all built: whether laby -h lists every action, whether each action's page is complete, whether every module has its help page, and whether the manual still matches what the runners do. Help written one branch at a time drifts, and at a busy terminal the operator has only the help to go on.

Remediation Plan

  1. Read the manual end to end against the built runners and fix every mismatch: each command, option, exit code and console message the release has, on both platforms.
  2. Make laby -h list every action of the release, and give each action a page (laby -h undo, laby -h keep, and so on): what it does, its options, one example and its exit codes.
  3. Give every module in the release its about.txt, in the order design 00, section 4 sets: what it checks, what it changes, why, what can go wrong, how to undo it, and what to do when it fails.
  4. Tests:
    • Each action in laby -h has its own page in both runners, with an example, and showing it never runs anything.
    • A module in a release with no about.txt, or one wider than 78 columns, fails the tests.
    • The Manuals CI job builds the man page, the help topic and both PDFs without warnings.
Lingua principale
PowerShell
Stelle
0
Fork
0
Merge medio
54m
PR unite (30g)
43

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di dotnetdork/Labyrinth

Tutte le issue di dotnetdork/Labyrinth

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.