Create a man page #146
Comments
wimpunk
added
the
discussion
|
I think we should also add the contents of the website to the repository. It's bit unpractical to maintain two repositories which contain related material. |
|
The idea was to move stuff from --help to the man page to minimize the help. Currently it is very long and may be confusing. |
|
I know the result is pretty long. But it should also be easy readable without the need to install a man page handler. Maybe I'm just getting old but I prefer a human readable document above a man page. Adding the info to ddclient makes it easier to update. Currently there's already a difference between what ddclient can do and what's in the documentation. I've always considered |
|
If you type git --help you are automatically show the man page or just the arguments. Also I expect everyone to have man installed. I never read --help and just searched through the script file. For me it is way to long to read and my less does not support mouse scroll so it is just inconvenient. There are tools which can convert man files to markdown or HTML (groff) and the other way (roff). |
Huh, that would be nice. That would make it possible to update the web page and the code in the same pull request.
How about the other way around: Create a Markdown or DocBook XML file and use it to generate three outputs: (1) an HTML page for https://ddclient.net, (2) a man page, and (3) plain text for substitution into the ddclient script (by a to-be-added "build" system). This shouldn't be too hard to do.
Debian policy says that everything should have a man page. To conform, the Debian package has a less-than-ideal stub man page. I think our users would greatly benefit from a fully fleshed-out man page. Another thought: Change |
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
Okay, I'll try to find out how to do it. I'll keep you posted.
That's a good way too. As long as it gets updated while changing ddclient I'm happy. Is there anyone volunteering in doing this ?
Actually, I'm not against a good man page but I would like to keep it usable without groff. So if we could do it like you suggested earlier by starting from a docbook or markdown and generate the outputs, I'm happy. |
I volunteer. PR #161 adds a build system that we can leverage for the XML/Markdown to troff/html/text conversion and the substitution into the ddclient script. Do you have a preference for DocBook XML vs. Ronn Markdown? (Or maybe something else?) Both DocBook and Ronn have built-in support for HTML and roff, and plain text can be generated from roff. Both will work on old platforms like CentOS 6, I think. Pros and cons:
I'm leaning toward Ronn-flavored Markdown for now. We can later migrate to DocBook XML if we need the extra power. |
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
This makes it easier to package ddclient, especially as enhancements are made such as unit tests or a man page. I chose GNU Autoconf and Automake mostly because I'm familiar with them, but also because I know they are well supported. Unfortunately they can be difficult to understand/maintain (especially Autoconf), so we may want to convert to something else later. Addresses ddclient#146, ddclient#147
|
This is a feature request and feature requests in the form of issues are no longer accepted. |
The output of
-helpis quite unwieldy. I think it would be good to move the examples to a man page to drastically shrink the amount of help text. The man page would also be a good place to clarify the config file format.The text was updated successfully, but these errors were encountered: