diff --git a/data/man1.template b/data/man1.template new file mode 100644 --- /dev/null +++ b/data/man1.template @@ -0,0 +1,77 @@ +.\" vim: ft=nroff.mustache +.Dd $Mdocdate$ +.Dt {{{title}}} 1 +.Os +.Sh NAME +{{#name.init}} +.Nm {{{.}}} , +{{/name.init}} +.Nm {{{name.last}}} +.Nd {{{name.description}}} +.Sh SYNOPSIS +.Nm +.Bk -words +{{#page.synopsis}} +{{{page.synopsis}}} +{{/page.synopsis}} +{{^page.commands}} +.Ek +{{/page.commands}} +{{#page.commands}} +.Ar command +.Ek +{{#page.commands.items}} +.Pp +.Nm +.Cm {{{name}}} +{{#synopsis}} +.Bk -words +{{{.}}} +.Ek +{{/synopsis}} +{{/page.commands.items}} +{{/page.commands}} +.Sh DESCRIPTION +{{#page.prologue}} +{{{.}}} +{{/page.prologue}} +{{#page.options}} +The options are as follows: +.Bl -tag -width {{{page.options.width}}} +{{#page.options.items}} +.It {{{head}}} +{{#body}} +{{{body}}} +{{/body}} +{{/page.options.items}} +.El +{{/page.options}} +{{#page.commands}} +.Ss COMMANDS +.Bl -tag -width {{{page.commands.width}}} +{{#page.commands.items}} +.It Cm {{{name}}} +{{#description}} +{{{description}}} +{{/description}} +{{/page.commands.items}} +.El +{{/page.commands}} +{{#page.environment}} +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width {{{page.environment.width}}} +{{#page.environment.items}} +.It {{{head}}} +{{#body}} +{{{body}}} +{{/body}} +{{/page.environment.items}} +.El +{{/page.environment}} +.Sh EXIT STATUS +.Ex -std +{{#page.epilogue}} +{{{.}}} +{{/page.epilogue}} diff --git a/data/man5.template b/data/man5.template new file mode 100644 --- /dev/null +++ b/data/man5.template @@ -0,0 +1,29 @@ +.\" vim: ft=nroff.mustache +.Dd $Mdocdate$ +.Dt {{{title}}} 5 +.Os +.Sh NAME +{{#name.init}} +.Nm {{{.}}} , +{{/name.init}} +.Nm {{{name.last}}} +.Nd {{{name.description}}} +{{#page.synopsis}} +.Sh SYNOPSIS +{{{.}}} +{{/page.synopsis}} +.Sh DESCRIPTION +{{#page.prologue}} +{{{.}}} +{{/page.prologue}} +.Bl -tag -width {{{page.configs.width}}} +{{#page.configs.items}} +.It {{{head}}} +{{#body}} +{{{body}}} +{{/body}} +{{/page.configs.items}} +.El +{{#page.epilogue}} +{{{.}}} +{{/page.epilogue}} diff --git a/examples/docker.1 b/examples/docker.1 new file mode 100644 --- /dev/null +++ b/examples/docker.1 @@ -0,0 +1,69 @@ +.\" vim: ft=nroff.mustache +.Dd $Mdocdate: September 20 2026 $ +.Dt DOCKER 1 +.Os +.Sh NAME +.Nm docker +.Nd a self\-sufficient runtime for containers +.Sh SYNOPSIS +.Nm +.Bk -words +.Op Fl \&Dv +.Op Fl c Ar string +.Op Fl H Ar string +.Op Fl l Ar string +.Op Fl Fl config= Ns Ar string +.Op Fl Fl tls +.Op Fl Fl tlscacert= Ns Ar string +.Op Fl Fl tlscert= Ns Ar string +.Op Fl Fl tlskey= Ns Ar string +.Op Fl Fl tlsverify +.Ar command +.Ek +.Pp +.Nm +.Cm run +.Pp +.Nm +.Cm exec +.Pp +.Nm +.Cm ps +.Sh DESCRIPTION +The options are as follows: +.Bl -tag -width indent +.It Fl c Ar string , Fl Fl context= Ns Ar string +Name of the context to use to connect to the daemon (overrides DOCKER_HOST env +var and default context set with "docker context use") +.It Fl D , Fl Fl debug +Enable debug mode +.It Fl H Ar string , Fl Fl host= Ns Ar string +Daemon socket to connect to +.It Fl l Ar string , Fl Fl log\-level= Ns Ar string +Set the logging level ("debug", "info", "warn", "error", "fatal") +.It Fl v , Fl Fl version +Print version information and quit +.It Fl Fl config= Ns Ar string +Location of client config files +.It Fl Fl tls +Use TLS; implied by \-\-tlsverify +.It Fl Fl tlscacert= Ns Ar string +Trust certs signed only by this CA +.It Fl Fl tlscert= Ns Ar string +Path to TLS certificate file +.It Fl Fl tlskey= Ns Ar string +Path to TLS key file +.It Fl Fl tlsverify +Use TLS and verify the remote +.El +.Ss COMMANDS +.Bl -tag -width indent +.It Cm run +Create and run a new container from an image +.It Cm exec +Execute a command in a running container +.It Cm ps +List containers +.El +.Sh EXIT STATUS +.Ex -std diff --git a/mdoc.cabal b/mdoc.cabal --- a/mdoc.cabal +++ b/mdoc.cabal @@ -1,6 +1,6 @@ cabal-version: 1.18 name: mdoc -version: 0.3.1.0 +version: 0.3.1.1 license: AGPL-3 license-file: COPYING maintainer: Pat Brisbin @@ -31,7 +31,10 @@ category: Text build-type: Simple extra-source-files: + data/man1.template + data/man5.template examples/crontab.5 + examples/docker.1 examples/example.1 examples/examplerc.5 examples/grep.1 @@ -72,6 +75,7 @@ Mdoc.Dump.Env Mdoc.Dump.Main Mdoc.Dump.Options + Mdoc.Examples.Docker Mdoc.Examples.Grep Mdoc.Examples.OptEnvConf Mdoc.Examples.Pass diff --git a/src/Mdoc/Data/Synopsis.hs b/src/Mdoc/Data/Synopsis.hs --- a/src/Mdoc/Data/Synopsis.hs +++ b/src/Mdoc/Data/Synopsis.hs @@ -64,9 +64,25 @@ unAnnotate $ vsep $ catMaybes - [ (".Op Fl" <+>) . pretty . esc . pack . toList <$> nonEmpty u.chars + [ (".Op Fl" <+>) . pretty . fixMacro . esc . pack . toList <$> nonEmpty u.chars , vsep . toList <$> nonEmpty (u.shorts <> u.longs <> u.args) ] + +-- | Fix for when short-switches accidentally become a macro name +-- +-- For example, @docker(1)@ has short switches @-D@ and @-v@, which become: +-- +-- @ +-- .Op Fl Dv +-- @ +-- +-- We have to escape the @Dv@ since it's a macro name. +-- +-- It's safe to do this always, I guess, but also easy to only do it if needed. +fixMacro :: Text -> Text +fixMacro t + | t `elem` macroNames = "\\&" <> t + | otherwise = t buildUsage :: [Described Positional] -> Usage ann buildUsage = foldl go mempty . sort diff --git a/src/Mdoc/Examples/Docker.hs b/src/Mdoc/Examples/Docker.hs new file mode 100644 --- /dev/null +++ b/src/Mdoc/Examples/Docker.hs @@ -0,0 +1,45 @@ +module Mdoc.Examples.Docker + ( docker1 + ) where + +import Mdoc.Prelude + +import Mdoc.Data.Named +import OptEnvConf qualified +import OptEnvConf.Mdoc qualified as OptEnvConf + +docker1 :: Named +docker1 = + mempty + & (<> OptEnvConf.getPage dockerOpt) + & name "docker" "a self-sufficient runtime for containers" + +{- FOURMOLU_DISABLE -} +dockerOpt :: OptEnvConf.Parser () +dockerOpt = void $ (,,,,,,,,,,,) + <$> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "config", OptEnvConf.metavar "string", OptEnvConf.help "Location of client config files", OptEnvConf.value "/home/patrick/.docker"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'c', OptEnvConf.long "context", OptEnvConf.metavar "string", OptEnvConf.help "Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with \"docker context use\")"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'D', OptEnvConf.long "debug", OptEnvConf.help "Enable debug mode"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'H', OptEnvConf.long "host", OptEnvConf.metavar "string", OptEnvConf.help "Daemon socket to connect to"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'l', OptEnvConf.long "log-level", OptEnvConf.metavar "string", OptEnvConf.help "Set the logging level (\"debug\", \"info\", \"warn\", \"error\", \"fatal\")", OptEnvConf.value "info"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tls", OptEnvConf.help "Use TLS; implied by --tlsverify"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscacert", OptEnvConf.metavar "string", OptEnvConf.help "Trust certs signed only by this CA", OptEnvConf.value "/home/patrick/.docker/ca.pem"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscert", OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS certificate file", OptEnvConf.value "/home/patrick/.docker/cert.pem"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlskey", OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS key file", OptEnvConf.value "/home/patrick/.docker/key.pem"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tlsverify", OptEnvConf.help "Use TLS and verify the remote"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'v', OptEnvConf.long "version", OptEnvConf.help "Print version information and quit"]) + <*> OptEnvConf.commands + [ OptEnvConf.command "run" "Create and run a new container from an image" runOpt + , OptEnvConf.command "exec" "Execute a command in a running container" execOpt + , OptEnvConf.command "ps" "List containers" psOpt + ] + +runOpt :: OptEnvConf.Parser () +runOpt = pure () + +execOpt :: OptEnvConf.Parser () +execOpt = pure () + +psOpt :: OptEnvConf.Parser () +psOpt = pure () +{- FOURMOLU_ENABLE -} diff --git a/src/Mdoc/Syntax/MacroName.hs b/src/Mdoc/Syntax/MacroName.hs --- a/src/Mdoc/Syntax/MacroName.hs +++ b/src/Mdoc/Syntax/MacroName.hs @@ -9,6 +9,7 @@ module Mdoc.Syntax.MacroName ( MacroName (..) , macroNameText + , macroNames -- * Pretty , prettyMacroName @@ -151,6 +152,9 @@ percent = ("%" <>) <$> T.stripPrefix "Percent" shown troff = T.stripPrefix "Troff'" shown bug = T.stripPrefix "Bug" shown + +macroNames :: [Text] +macroNames = map macroNameText [minBound .. maxBound] prettyMacroName :: MacroName -> Doc Ann prettyMacroName = pretty . macroNameText diff --git a/test/Mdoc/ExamplesSpec.hs b/test/Mdoc/ExamplesSpec.hs --- a/test/Mdoc/ExamplesSpec.hs +++ b/test/Mdoc/ExamplesSpec.hs @@ -19,6 +19,7 @@ import Data.Time (fromGregorian) import Mdoc import Mdoc.Data.Named +import Mdoc.Examples.Docker import Mdoc.Examples.Grep import Mdoc.Examples.OptEnvConf import Mdoc.Examples.Pass @@ -38,6 +39,7 @@ it "grep.1" $ exampleGolden man1 grep1 1 it "example.1" $ exampleGolden man1 example1 1 it "pass.1" $ exampleGolden man1 pass1 1 + it "docker.1" $ exampleGolden man1 docker1 1 it "conf.5" $ exampleGolden man5 conf5 5 it "example.5" $ exampleGolden man5 example5 5 it "person.5" $ exampleGolden man5 person5 5