[Bug 225780] www/caddy: Improve post-installation usability/experience (missing documentation)

[bugzilla-noreply at freebsd.org]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=225780

--- Comment #5 from Chris Hutchinson <portmaster at bsdforge.com> ---
(In reply to Fabian Freyer from comment #3)
> It seems there is an issue [1] open for this upstream, my apologies for
> missing that earlier. I'll include the manpage once it exists upstream.
> 
> I wasn't aware that software shipping any man pages or other documentation
> were out of scope for the ports tree, and that inclusion of such would be
> setting a dangerous precedent. On a quick, cursory, re-visitation of the
> Porter's Handbook [2], I didn't find any policies there - did I miss
> something, or is this some sort of unwritten rule?

When I first began the attempt to become a maintainer, some 5yrs ago. I
created a port that didn't have any docs (man, or otherwise). Not unlike
your port; everything was online. I was informed that policy was such
that this sort of thing was forbidden, for what should seem obvious
reasons. The handbook wasn't as as grandiose back then, and since my
mentor was a well seasoned, I didn't even look to question him. :-)
So I guess it just seemed like TRTTD (the right thing to do).

> 
> I agree that including documentation where possible is always beneficial.
> Where would you suggest installing the README.md[3]
/usr/local/share/docs/caddy

The README should suffice if it provides usage instructions, and a link
to the online documentation IMHO it should provide an apology for not
adding it to their distribution -- they should apologize, not you. :-)

> and/or how would you
> suggest referencing the online documentation[4]?

IMHO it should really be contained in the README. But if not, adding a
message.in that ehoes
"the full documentation for caddy can be found online at:
http://wherever-the-caddy-docs-are-inline/
See also
/usr/local/share/docs/caddy/README for basic usage instructions"

> 
> [1] https://github.com/mholt/caddy/issues/1876
> [2] https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/
> [3] https://github.com/mholt/caddy/blob/master/README.md
> [4] https://caddyserver.com/docs

All the best.

--Chris

-- 
You are receiving this mail because:
You are the assignee for the bug.