man page

[carlwgeorge]

1. What version of Caddy are you using (caddy -version)?

0.10.9

2. What are you trying to do?

man caddy

Having a man page available would be useful for quick reference on servers and would help comply with distro packaging guidelines.

[tobya]

Thank you for the request. We can add it to the list, if anyone was willing to put something together that could be discussed that would be great.

[fakeid30]

@tobya I'm willing to write the man page.

[tobya]

@fakeid30 That's great, maybe post it here for comments when done.

[fakeid30]

@tobya Hmm, I need a bit of a guide as to how you want me to do it. Can we talk on email ?

[tobya]

I dont know much about man pages, but if you take a stab at it and read up about their format you could get a basic draft together. Look at other man pages to give you an idea of the sort of information that might be useful to have in a man page.

[theodesp]

How about using https://pandoc.org/ to convert to man pages? Is that viable?

[tobya]

Looks promising. It would certainly make the arcane world of man pages a little easier!

[4470]

Uploading pandoc-2.9.2.1.tar.gz…
https://pandoc.org/

[tobya]

@4470 Thank you for your note. Have you managed to work on the man page?

[francislavoie]

@carlwgeorge do you still consider this relevant for v2? Is caddy help enough?

[carlwgeorge]

Yes, it's absolutely still relevant. Man pages are the de facto standard on Linux. They are either required or recommended for distribution packaging guidelines.

• https://docs.fedoraproject.org/en-US/packaging-guidelines/#_manpages
• https://www.debian.org/doc/debian-policy/ch-docs.html#manual-pages

Speaking for myself personally, when I need to check on the usage or flags of a command, I check the following resources in order.

1. man <command>
2. <command> --help
3. Google

[mholt]

Anyone is welcome to work on this. :)

Dunno if this'll help: https://godoc.org/within.website/x/internal/manpage

[pymnh]

I will look into writing manpages, at least for cli-usage but ideally for also for config/caddyfile.

[pymnh]

Dunno if this'll help: https://godoc.org/within.website/x/internal/manpage

Very useful. thanks

Small update on this:
I went on adding a man subcommand, like this:

	RegisterCommand(Command{
		Name:  "man",
		Func:  cmdMan,
		Usage: "[--force]",
		Short: "Print manual pages for Caddy",
                Long: `
Prints manual pages for Caddy and its available subcommands into current directory. In case --force flag
ist set, existing man pages will be overwritten.`,
                ..
	})

cmdMan then itereates through commands and the main command and generates templates. Mostly works as intended, but I'm a total newbie to Go and need to familiarize myself with coding style and error handling before I submit a PR.

Is the general direction alright?

[mholt]

That sounds like a good approach, yeah. I don't know much about generating man pages, but I suppose that's as good a way as any to do it.

Am trying to decide if this will be used enough to merit inclusion into the standard Caddy distribution or if it should be a third party plugin.

[pymnh]

Am trying to decide if this will be used enough to merit inclusion into the standard Caddy distribution or if it should be a third party plugin.

Makes sense, target users for this feature would be distribution maintainers only.

I have opened a PR, caddyserver/caddy#4316 with my current draft, I guess it should work out to rewrite it as module. Just let me know

[mholt]

Good point, so yeah, probably an external module.

[francislavoie]

I'll close this, because both the .deb and .rpm have the manpage bundled, via the caddy manpage command which can generate it. See e06ce61 for example.