MIME-Version: 1.0
References: <53248902.4050200@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1
Message-ID:  <CACKZBPVDQzv4YzuBJxv7kv-=vLjH_gxb0RCvhEwbnnaF2uzAAQ@mail.gmail.com>
Date:         Sat, 15 Mar 2014 23:18:17 +0100
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender: Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From: Michiel Helvensteijn <mhelvens@GMAIL.COM>
Subject: Re: Documenting 'locally added' expl3 variants
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <53248902.4050200@morningstar2.co.uk>
Precedence: list
Content-Transfer-Encoding: quoted-printable
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

On Sat, Mar 15, 2014 at 6:08 PM, Joseph Wright
<joseph.wright@morningstar2.co.uk> wrote:

> Working systematically, I notice that I use a few variants of core expl=
3
> commands that have to be created. Based on the 'document everything
> public' principle, these should be mentioned (they have 'public'
> function names). On the other hand, they are 'nothing to do with me' as
> all I'm doing is something like
>
>   \cs_generate_variant:Nn \some_team_function:n { V }

Would you have generated this variant for the public interface even if
you didn't need it internally? That is, does it make sense on its own?
If so, document it. If not, don't document it.

If you do document it, you acknowledge it as part of the public
interface, and make it harder to get rid of in the future. If people
need \some_team_function:V, they can generate their own variant (which
is an idempotent operation, so that's fine). They might discover that
it already exists, but they shouldn't rely on this if it is
undocumented.

Just my 2=A2.

--=20
www.mhelvens.net