LATEX-L Archives

Mailing list for the LaTeX3 project

LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

Options: Use Forum View

Use Monospaced Font
Show Text Part by Default
Condense Mail Headers

Message: [<< First] [< Prev] [Next >] [Last >>]
Topic: [<< First] [< Prev] [Next >] [Last >>]
Author: [<< First] [< Prev] [Next >] [Last >>]

Print Reply
Sender:
Mailing list for the LaTeX3 project <[log in to unmask]>
Date:
Sat, 15 Mar 2014 23:18:17 +0100
Reply-To:
Mailing list for the LaTeX3 project <[log in to unmask]>
Message-ID:
Subject:
MIME-Version:
1.0
Content-Transfer-Encoding:
8bit
In-Reply-To:
Content-Type:
text/plain; charset=ISO-8859-1
From:
Michiel Helvensteijn <[log in to unmask]>
Parts/Attachments:
text/plain (27 lines)
On Sat, Mar 15, 2014 at 6:08 PM, Joseph Wright
<[log in to unmask]> wrote:

> Working systematically, I notice that I use a few variants of core expl3
> 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¢.

-- 
www.mhelvens.net

ATOM RSS1 RSS2