As pointed out in https://github.com/systemd/systemd/issues/29814, we need to
use phrases are are meaningful on their own, because the man page formatter
creates a list at the bottom. With <ulink>see docs</ulink>, we end up with:
NOTES:
1. see docs
https://some.url/page
2. see docs
https://some.url/page2
which is not very useful :(
Also, the text inside the tag should not include punctuation.
Python helper:
from xml_helper import xml_parse
for p in glob.glob('../man/*.xml'):
t = xml_parse(p)
ulinks = t.iterfind('.//ulink')
for ulink in ulinks:
if ulink.text is None: continue
text = ' '.join(ulink.text.split())
print(f'{p}: {text}')
As I noticed a lot of missing information when trying to implement checking
for missing info. I reimplemented the version information script to be more
robust, and here is the result.
Follow up to ec07c3c80b
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
serve stale feature to keep the DNS resource records beyond TTL to return them as stale records in case of upstream server is not reachable or returns negative response.
SD_RESOLVED_NO_STALE flag has been added to disable serving stale records via dbus.
added serve stale test cases to TEST-75-RESOLVED
Fixes: #21815
When low-level RR resolution is requested from "resolvectl query" via
"--type=" or "--class=" no search domain logic is applied and no IDNA
translation.
Explain this in detail in the documentation, and also mentions this when
users attempt to resolve single-label names or names with international
characters in the output.
I believe the current behaviour is correct, but it is indeed surprising.
Hence the documentation and output improvement.
Fixes: #11325#10737
It's not that I think that "hostname" is vastly superior to "host name". Quite
the opposite — the difference is small, and in some context the two-word version
does fit better. But in the tree, there are ~200 occurrences of the first, and
>1600 of the other, and consistent spelling is more important than any particular
spelling choice.
This is useful to raise the log level for a single transaction or a few,
without affecting other state of the resolved as a restart would.
The log level can only be set, I didn't bother with having the ability
to restore the original as in pid1.
Add manpages.debian.org as a man citeref "project", so we can refer to man
pages hosted there. resolvconf(8) doesn't seem to appear on any of the ones we
currently have defined.
We are doing a trick, where our man page is installed as resolvconf(1), and
we refer the reader to resolvconf(8). This can be pretty confusing, so the
least we can do is to provide a non-broken symlink ;)
v2:
- link to manpages.d.o instead of manpages.ubuntu.com, because debian is the
upstream here, and because with debian we can use /unstable/ as the version,
and ubuntu doesn't seem to have any such shortcut, so the version would need
to be periodically updated.
When someone knows how the whole ecosystem works, this is understandable.
But for someone coming from a system where resolvconf updates /etc/resolv.conf
directly, this can be rather surprising.
For https://bugzilla.redhat.com/show_bug.cgi?id=1815605.
For executables which take a verb, we should list the verbs first, and
then options which modify those verbs second. The general layout of
the man page is from general description to specific details, usually
Overview, Commands, Options, Return Value, Examples, References.
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
No need to waste space, and uniformity is good.
$ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
You can only have one listitem in each varlistentry.
xmllint says:
resolvectl.xml:269: element varlistentry: validity error : Element varlistentry content does not follow the DTD, expecting (term+ , listitem), got (term term term term term term term listitem listitem listitem )
The current CLI does not support a way to clear these lists, since without any
additional arguments, the command will list the current values.
Introduce a new way to clear the lists by passing a single '' argument to these
subcommands.
Update the man page to document this.
Tested:
$ build/resolvectl domain eth1
Link 3 (eth1): ~.
$ build/resolvectl domain eth1 ''
$ build/resolvectl domain eth1
Link 3 (eth1):
$ build/resolvectl domain eth1 '~.' '~example.com'
$ build/resolvectl domain eth1
Link 3 (eth1): ~. ~example.com
$ build/resolvectl domain eth1 ''
$ build/resolvectl domain eth1
Link 3 (eth1):
$ build/resolvectl domain eth1 '~.'
$ build/resolvectl domain eth1
Link 3 (eth1): ~.
And similar for "dns" and "nta".
Docbook styles required those to be present, even though the templates that we
use did not show those names anywhere. But something changed semi-recently (I
would suspect docbook templates, but there was only a minor version bump in
recent years, and the changelog does not suggest anything related), and builds
now work without those entries. Let's drop this dead weight.
Tested with F26-F29, debian unstable.
$ perl -i -0pe 's/\s*<authorgroup>.*<.authorgroup>//gms' man/*xml
These lines are generally out-of-date, incomplete and unnecessary. With
SPDX and git repository much more accurate and fine grained information
about licensing and authorship is available, hence let's drop the
per-file copyright notice. Of course, removing copyright lines of others
is problematic, hence this commit only removes my own lines and leaves
all others untouched. It might be nicer if sooner or later those could
go away too, making git the only and accurate source of authorship
information.
This part of the copyright blurb stems from the GPL use recommendations:
https://www.gnu.org/licenses/gpl-howto.en.html
The concept appears to originate in times where version control was per
file, instead of per tree, and was a way to glue the files together.
Ultimately, we nowadays don't live in that world anymore, and this
information is entirely useless anyway, as people are very welcome to
copy these files into any projects they like, and they shouldn't have to
change bits that are part of our copyright header for that.
hence, let's just get rid of this old cruft, and shorten our codebase a
bit.
