PR#8: Add patch for apachectl man page - rpms/httpd

rpms / httpd

#8 Add patch for apachectl man page

Merged 4 years ago by jorton. Opened 4 years ago by ferdnyc.

Unknown source apachectl-manpage into master

Add man page for Fedora apachectl

FeRD (Frank Dana) • 4 years ago

11b0ed9

apachectl.xml

file added

+173

		`@@ -0,0 +1,173 @@`
		`+ <?xml version='1.0' encoding='UTF-8' ?>`
		`+ <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"`
		`+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">[`
		`+`
		`+ ]>`
		`+ <!--`
		`+ Copyright 2018 Red Hat, Inc.`
		`+`
		`+ Licensed to the Apache Software Foundation (ASF) under one or more`
		`+ contributor license agreements. See the NOTICE file distributed with`
		`+ this work for additional information regarding copyright ownership.`
		`+ The ASF licenses this file to You under the Apache License, Version 2.0`
		`+ (the "License"); you may not use this file except in compliance with`
		`+ the License. You may obtain a copy of the License at`
		`+`
		`+ http://www.apache.org/licenses/LICENSE-2.0`
		`+`
		`+ Unless required by applicable law or agreed to in writing, software`
		`+ distributed under the License is distributed on an "AS IS" BASIS,`
		`+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.`
		`+ See the License for the specific language governing permissions and`
		`+ limitations under the License.`
		`+ -->`
		`+ <refentry>`
		`+ <refentryinfo>`
		`+ <title>apachectl</title>`
		`+ <productname>httpd</productname>`
		`+ <corpauthor>Apache Software Foundation</corpauthor>`
		`+ <editor><contrib>Fedora man page</contrib><surname>Dana</surname><firstname>Frank</firstname><email>ferdnyc@gmail.com</email></editor>`
		`+ </refentryinfo>`
		`+`
		`+ <refmeta>`
		`+ <refentrytitle>apachectl</refentrytitle>`
		`+ <manvolnum>8</manvolnum>`
		`+ </refmeta>`
		`+`
		`+ <refnamediv>`
		`+ <refname>apachectl</refname>`
		`+ <refpurpose>Server control interface for httpd</refpurpose>`
		`+ </refnamediv>`
		`+`
		`+ <refsynopsisdiv id='synopsis'>`
		`+ <cmdsynopsis>`
		`+ <command>apachectl</command>`
		`+ <arg choice='opt'><replaceable>command</replaceable> </arg>`
		`+ <sbr/>`
		`+ </cmdsynopsis>`
		`+ </refsynopsisdiv>`
		`+`
		`+ <!-- body begins here -->`
		`+ <refsect1 id='description'>`
		`+ <title>DESCRIPTION</title>`
		`+`
		`+ <para><command>apachectl</command> is a front end to the Apache HyperText`
		`+ Transfer Protocol (HTTP) server. It is designed to help the`
		`+ administrator control the functioning of the Apache`
		`+ <command>httpd</command> daemon.</para>`
		`+`
		`+ <para>The <command>apachectl</command> script takes one-word arguments like`
		`+ <option>start</option>,`
		`+ <option>restart</option>, and`
		`+ <option>stop</option>, and translates them`
		`+ into appropriate signals to <command>httpd</command>.</para>`
		`+`
		`+ <para>The <command>apachectl</command> script returns a 0 exit value on`
		`+ success, and >0 if an error occurs.</para>`
		`+`
		`+ </refsect1>`
		`+`
		`+ <refsect1 id='options'>`
		`+ <title>OPTIONS</title>`
		`+ <variablelist remap='TP'>`
		`+ <varlistentry>`
		`+ <term><option>start</option></term>`
		`+ <listitem>`
		`+ <para>Start the Apache <command>httpd</command> daemon. Gives an error if it`
		`+ is already running. This is equivalent to <command>systemctl start httpd.service</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>stop</option></term>`
		`+ <listitem>`
		`+ <para>Stops the Apache <command>httpd</command> daemon. This is equivalent to`
		`+ <command>systemctl stop httpd.service</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>restart</option></term>`
		`+ <listitem>`
		`+ <para>Restarts the Apache <command>httpd</command> daemon. If the daemon is`
		`+ not running, it is started. This is equivalent`
		`+ to <command>systemctl restart httpd.service</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>status</option></term>`
		`+ <listitem>`
		`+ <para>Displays a brief status report. This is equivalent to <command>systemctl status httpd.service.</command></para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>graceful</option></term>`
		`+ <listitem>`
		`+ <para>Gracefully restarts the Apache <command>httpd</command> daemon. If the`
		`+ daemon is not running, it is started. This differs from a normal`
		`+ restart in that currently open connections are not aborted. A side`
		`+ effect is that old log files will not be closed immediately. This`
		`+ means that if used in a log rotation script, a substantial delay may`
		`+ be necessary to ensure that the old log files are closed before`
		`+ processing them. This is equivalent to`
		`+ <command>systemctl kill --signal=SIGUSR1 --kill-who=main httpd.service</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>graceful-stop</option></term>`
		`+ <listitem>`
		`+ <para>Gracefully stops the Apache <command>httpd</command> daemon.`
		`+ This differs from a normal stop in that currently open connections are not`
		`+ aborted. A side effect is that old log files will not be closed immediately.`
		`+ This is equivalent to`
		`+ <command>systemctl kill --signal=SIGWINCH --kill-who=main httpd.service</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>configtest</option></term>`
		`+ <listitem>`
		`+ <para>Run a configuration file syntax test. It parses the configuration`
		`+ files and either reports <literal>Syntax Ok</literal>`
		`+ or detailed information about the particular syntax error. This is`
		`+ equivalent to <command>httpd -t</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+ </variablelist>`
		`+`
		`+ <para>The following options were available in earlier versions but have been removed.</para>`
		`+`
		`+ <variablelist remap='TP'>`
		`+ <varlistentry>`
		`+ <term><option>fullstatus</option></term>`
		`+ <listitem>`
		`+ <para>Displays a full status report from <literal>mod_status</literal>.`
		`+ For this to work, you need to have <literal>mod_status</literal> enabled`
		`+ on your server and a text-based browser such as <command>lynx</command>`
		`+ available on your system. The URL used to access the status report`
		`+ can be set by editing the <literal>STATUSURL</literal> variable in the`
		`+ script.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+`
		`+ <varlistentry>`
		`+ <term><option>startssl</option></term>`
		`+ <listitem>`
		`+ <para>To start <command>httpd</command> with SSL support, you should edit`
		`+ your configuration file to include the relevant directives and then`
		`+ use the normal <command>apachectl start</command>.</para>`
		`+ </listitem>`
		`+ </varlistentry>`
		`+ </variablelist>`
		`+ </refsect1>`
		`+`
		`+ <refsect1 id='bugs'>`
		`+ <title>BUGS</title>`
		`+ <para>Please report bugs by filing an issue against the "httpd" component of the "Fedora"`
		`+ project, in <ulink url='https://bugzilla.redhat.com/'>RedHat Bugzilla</ulink>.</para>`
		`+ </refsect1>`
		`+`
		`+ </refentry>`

httpd.spec

file modified

+9 -2

		`@@ -13,7 +13,7 @@`
		`Summary: Apache HTTP Server`
		`Name: httpd`
		`Version: 2.4.41`
		`- Release: 9%{?dist}`
		`+ Release: 10%{?dist}`
		`URL: https://httpd.apache.org/`
		`Source0: https://www.apache.org/dist/httpd/httpd-%{version}.tar.bz2`
		`Source1: https://www.apache.org/dist/httpd/httpd-%{version}.tar.bz2.asc`
		`@@ -59,6 +59,7 @@`
		`Source44: httpd@.service`
		`Source45: config.layout`
		`Source46: apachectl.sh`
		`+ Source47: apachectl.xml`

		`# build/scripts patches`
		`Patch2: httpd-2.4.9-apxs.patch`
		`@@ -269,6 +270,9 @@`
		`xmlto man $RPM_SOURCE_DIR/htcacheclean.service.xml`
		`xmlto man $RPM_SOURCE_DIR/httpd.service.xml`

		`+ # apachectl.xml => apachectl.8`
		`+ xmlto man %{SOURCE47}`
		`+`
		`: Building with MMN %{mmn}, MMN-ISA %{mmnisa}`
		`: Default MPM is %{mpm}, vendor string is '%{vstring}'`

		`@@ -498,7 +502,7 @@`
		`# Install man pages`
		`install -d $RPM_BUILD_ROOT%{_mandir}/man8 $RPM_BUILD_ROOT%{_mandir}/man5`
		`install -m 644 -p httpd.service.8 httpd-init.service.8 httpd.socket.8 \`
		`- httpd@.service.8 htcacheclean.service.8 \`
		`+ httpd@.service.8 htcacheclean.service.8 apachectl.8 \`
		`$RPM_BUILD_ROOT%{_mandir}/man8`
		`install -m 644 -p httpd.conf.5 \`
		`$RPM_BUILD_ROOT%{_mandir}/man5`
		`@@ -749,6 +753,9 @@`
		`%{_rpmconfigdir}/macros.d/macros.httpd`

		`%changelog`
		`+ * Sat Dec 7 2019 FeRD (Frank Dana) <ferdnyc@gmail.com> - 2.4.41-10`
		`+ - apachectl: Add man page for Fedora version`
		`+`
		`* Thu Nov 21 2019 Joe Orton <jorton@redhat.com> - 2.4.41-9`
		`- mod_ssl: fix request body buffering w/TLSv1.3 PHA (#1775146)`

ferdnyc commented 4 years ago

The apachectl man page packaged with Apache is wildly incorrect now that we're packaging our own, pared-down script.

The comments in the file at docs/man/apachectl.8 included giant "DO NOT EDIT, GENERATED FROM XML SOURCE" warnings, but I couldn't find those XML sources anywhere in the distribution, nor any process that appeared to be meant to regenerate the file, so I just edited it in-place anyway. The attached patch:

updates the content to remove all references to non-"SysV mode" (or, indeed, to SysV mode as such), as well as no-longer-accepted command-line flags
relegates apachectl fullstatus to the "previously supported" commands list
Omits some potentially-offensive language flagged by the Alex tool ("simple", "die")
Updates the command equivalencies from their complex apachectl alternatives to the corresponding systemctl or httpd commands they invoke.

I didn't edit the corresponding section of the manual, so the documentation is still out of date (and now inconsistent, to boot), but at least the man page doesn't contain loads of wrong information anymore.

Some of the information I left in the description of the graceful command may still be out-of-date, though.

ferdnyc commented 4 years ago

In light of the discussion in #7 , and because it's really only our apachectl that the updated man page documents, I'm now wondering if it wouldn't actually be better if we just replace the distributed apachectl.8 man page with our own version (included as a Source# file) instead of patching the distributed version, the same way our apachectl.sh script replaces the distributed apachectl command.

Any further changes made to apachectl.8 in the source distribution won't apply to our apachectl any more than the current contents do, so there's no real point in patching the original file — in reality it's 100% non-representative of the apachectl we install, even though some of it happens to apply because we chose to implement the same commands supported in the original tool.

jorton commented 4 years ago

Thanks for opening the PR!

In light of the discussion in #7 , and because it's really only our apachectl that the updated man page documents, I'm now wondering if it wouldn't actually be better if we just replace the distributed apachectl.8 man page with our own version (included as a Source# file) instead of patching the distributed version, the same way our apachectl.sh script replaces the distributed apachectl command.
Any further changes made to apachectl.8 in the source distribution won't apply to our apachectl any more than the current contents do, so there's no real point in patching the original file — in reality it's 100% non-representative of the apachectl we install, even though some of it happens to apply because we chose to implement the same commands supported in the original tool.

Yes I agree that would be a much better plan. The man page sources are upstream http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/programs/apachectl.xml?view=markup but unfortunately not docbook XML. My preference would be to convert that to docbook XML and build it the same way we build httpd.service(8) etc, though it'll be a bit of an effort to do that conversion.

rebased onto 11b0ed9

4 years ago

ferdnyc commented 4 years ago

@jorton

Actually, it wasn't that bad. Updated commit pushed, replacing the patch with an apachectl.xml that's built into apachectl.8 and installed in place of the dist version.

I cribbed heavily from your own httpd.service.xml and httpd.conf.xml, as well as dbus-launch.1.xml.in. Consider it a WIP, though, I'll happily make any changes needed.

ferdnyc commented 4 years ago

@jorton

Whenever you're able (definitely low-priority), could you take a look at 11b0ed9 on this PR? As discussed it now includes a Docbook XML version of the apachectl(8) man page, specifically tailored to the Fedora systemd-based version of the command, which is built and installed in place of the man page included in the source distribution.

Pull-Request has been merged by jorton

4 years ago

jorton commented 4 years ago

Thanks so much for doing this @ferdnyc - awesome work!

I merged this, made some further tweaks in 73594f6 and kicked off a build.

One question - are you definitely sure you want your e-mail address listed in the man page? Don't think it's a problem if you are OK with it, but wanted to double check.

jorton commented 4 years ago

https://src.fedoraproject.org/rpms/httpd/c/73594f69fff617d374554b08158ee6fd644b98c2?branch=master

ferdnyc commented 4 years ago

@jorton

Yeah, you know what, I probably don't. Thanks for pointing that out!

Honestly that whole <editor>...</editor> block can be dropped, I'm really not concerned about credit or whatever. It was actually more about offering myself up as the person to blame for any errors or issues with the resulting text. :wink: