From: Ingo Schwarze <schwarze@usta.de>
To: Yuri Pankov <yuripv@gmx.com>
Cc: mdocml-discuss <discuss@mdocml.bsd.lv>
Subject: Re: move roff sections to a separate file
Date: Tue, 30 May 2017 01:47:17 +0200 [thread overview]
Message-ID: <20170529234717.GA54102@athene.usta.de> (raw)
In-Reply-To: <b34a95bc-8e9f-66b0-27d0-0fb01fed6ad1@gmx.com>
Hi Yuri,
Yuri Pankov wrote on Tue, May 30, 2017 at 01:14:35AM +0300:
> I'd like a propose a small change which would simplify maintaining a
> downstream version for us (as we need it modified and with a bit changed
> order) - move list of sections (roff_sec) and their descriptions (secnames)
> to separate file which we keep without a need to sync with upstream,
> roffsec.in. Patch is pretty straightforward and simply moves both there.
I see why such small differences can be a bother in maintenance,
but i don't like the direction this is going.
1. I'd like to encourage more consistency in manual page organization
across different systems, not facilitate divergence. Section
naming and ordering is an area where existing differences are
relatively mild, and making this aggressively configurable
really seems like pushing into the wrong direction to me.
2. Besides harming users by promoting gratuitious differences among
platforms, such configurability also impedes flexibility of
development because - even keeping the user-visibile functionality
constant - the implementation cannot be modified when *.in-style
interfaces are promised to downstream systems.
3. Technically, i don't like the concept of *.in files at all.
They make reading the code harder, as they are neither fish nor
fowl, neither proper, readable C code, nor proper, readable *.h
headers. I want to slowly get rid of them. I have deleted a
few already and hope to continue in that direction, even if not
with terribly high priority. But i certainly don't want to add
any more of them.
4. Your specific patch is incorrect.
"static const char * const secnames[SEC__MAX]"
is not a declaration, but a definition.
So if it goes into an *.in file, that *.in file cannot be
included in any *.h file, but only in one *.c file, because
otherwise every *.o file using the *.h file gets its own copy
of the array.
But enum roff_sec *is* needed in roff.h, so you are stuck.
I don't think you should try to fix the technicality (4) because
that will only make the patch yet uglier, aggravate (3), and not
solve the more fundamental issues (1) and (2) in the least.
To help finding a solution, i should like to understand the scope
of the issue better.
Which sections specificially do you want to order in which
non-standard way?
Is there any other, specific issue except ordering that you would
like to change? If so, which one?
Note that, if you simply use some additional, non-standard sections
in some pages, i'm not convinced they need to be listed at all.
They should work just fine as SEC_CUSTOM.
Then again, if a section name is sufficiently widespread, we
usually carry it even if it is not used in every system (e.g. LIBRARY).
If you think there is such a case of a section name used by many, but
not by all systems, that ought to be added, which one is it?
Yours,
Ingo
> commit 369032da926596cc6cec2a5615fe3afd9f6083db
> Author: Yuri Pankov <yuri.pankov@nexenta.com>
> Date: Tue May 30 01:02:14 2017 +0300
>
> move section list to separate file
>
> diff --git a/mdoc_validate.c b/mdoc_validate.c
> index 1d3d81e..ede6863 100644
> --- a/mdoc_validate.c
> +++ b/mdoc_validate.c
> @@ -251,33 +251,6 @@ static const enum roff_tok rsord[RSORD_MAX] = {
> MDOC__O
> };
>
> -static const char * const secnames[SEC__MAX] = {
> - NULL,
> - "NAME",
> - "LIBRARY",
> - "SYNOPSIS",
> - "DESCRIPTION",
> - "CONTEXT",
> - "IMPLEMENTATION NOTES",
> - "RETURN VALUES",
> - "ENVIRONMENT",
> - "FILES",
> - "EXIT STATUS",
> - "EXAMPLES",
> - "DIAGNOSTICS",
> - "COMPATIBILITY",
> - "ERRORS",
> - "SEE ALSO",
> - "STANDARDS",
> - "HISTORY",
> - "AUTHORS",
> - "CAVEATS",
> - "BUGS",
> - "SECURITY CONSIDERATIONS",
> - NULL
> -};
> -
> -
> void
> mdoc_node_validate(struct roff_man *mdoc)
> {
> diff --git a/roff.h b/roff.h
> index f0c2bf4..8f90faa 100644
> --- a/roff.h
> +++ b/roff.h
> @@ -16,6 +16,8 @@
> * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
> */
>
> +#include "roffsec.in"
> +
> struct ohash;
> struct mdoc_arg;
> union mdoc_data;
> @@ -26,33 +28,6 @@ enum roff_macroset {
> MACROSET_MAN
> };
>
> -enum roff_sec {
> - SEC_NONE = 0,
> - SEC_NAME,
> - SEC_LIBRARY,
> - SEC_SYNOPSIS,
> - SEC_DESCRIPTION,
> - SEC_CONTEXT,
> - SEC_IMPLEMENTATION, /* IMPLEMENTATION NOTES */
> - SEC_RETURN_VALUES,
> - SEC_ENVIRONMENT,
> - SEC_FILES,
> - SEC_EXIT_STATUS,
> - SEC_EXAMPLES,
> - SEC_DIAGNOSTICS,
> - SEC_COMPATIBILITY,
> - SEC_ERRORS,
> - SEC_SEE_ALSO,
> - SEC_STANDARDS,
> - SEC_HISTORY,
> - SEC_AUTHORS,
> - SEC_CAVEATS,
> - SEC_BUGS,
> - SEC_SECURITY,
> - SEC_CUSTOM,
> - SEC__MAX
> -};
> -
> enum roff_type {
> ROFFT_ROOT,
> ROFFT_BLOCK,
> diff --git a/roffsec.in b/roffsec.in
> new file mode 100644
> index 0000000..6fd4172
> --- /dev/null
> +++ b/roffsec.in
> @@ -0,0 +1,70 @@
> +/*
> + * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
> + * Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
> + * Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
> + *
> + * Permission to use, copy, modify, and distribute this software for any
> + * purpose with or without fee is hereby granted, provided that the above
> + * copyright notice and this permission notice appear in all copies.
> + *
> + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
> + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
> + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
> + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
> + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
> + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
> + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
> + */
> +
> +enum roff_sec {
> + SEC_NONE = 0,
> + SEC_NAME,
> + SEC_LIBRARY,
> + SEC_SYNOPSIS,
> + SEC_DESCRIPTION,
> + SEC_CONTEXT,
> + SEC_IMPLEMENTATION, /* IMPLEMENTATION NOTES */
> + SEC_RETURN_VALUES,
> + SEC_ENVIRONMENT,
> + SEC_FILES,
> + SEC_EXIT_STATUS,
> + SEC_EXAMPLES,
> + SEC_DIAGNOSTICS,
> + SEC_COMPATIBILITY,
> + SEC_ERRORS,
> + SEC_SEE_ALSO,
> + SEC_STANDARDS,
> + SEC_HISTORY,
> + SEC_AUTHORS,
> + SEC_CAVEATS,
> + SEC_BUGS,
> + SEC_SECURITY,
> + SEC_CUSTOM,
> + SEC__MAX
> +};
> +
> +static const char * const secnames[SEC__MAX] = {
> + NULL,
> + "NAME",
> + "LIBRARY",
> + "SYNOPSIS",
> + "DESCRIPTION",
> + "CONTEXT",
> + "IMPLEMENTATION NOTES",
> + "RETURN VALUES",
> + "ENVIRONMENT",
> + "FILES",
> + "EXIT STATUS",
> + "EXAMPLES",
> + "DIAGNOSTICS",
> + "COMPATIBILITY",
> + "ERRORS",
> + "SEE ALSO",
> + "STANDARDS",
> + "HISTORY",
> + "AUTHORS",
> + "CAVEATS",
> + "BUGS",
> + "SECURITY CONSIDERATIONS",
> + NULL
> +};
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
next prev parent reply other threads:[~2017-05-29 23:47 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-05-29 22:14 Yuri Pankov
2017-05-29 23:47 ` Ingo Schwarze [this message]
2017-05-30 0:09 ` Yuri Pankov
2017-05-30 1:15 ` Ingo Schwarze
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170529234717.GA54102@athene.usta.de \
--to=schwarze@usta.de \
--cc=discuss@mdocml.bsd.lv \
--cc=yuripv@gmx.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).