Sender: |
|
Date: |
Sun, 16 Mar 2014 10:09:43 +0100 |
Reply-To: |
|
Message-ID: |
|
Subject: |
|
MIME-Version: |
1.0 |
Content-Transfer-Encoding: |
7bit |
In-Reply-To: |
|
Content-Type: |
text/plain; charset=ISO-8859-1; format=flowed |
From: |
|
Parts/Attachments: |
|
|
Am 15.03.2014 18:52, schrieb Joseph Wright:
> On 15/03/2014 17:41, Frank Mittelbach wrote:
>>> How do other people see this?
>>
>> we are talking about variants of kernel functions correct?
>
> Yes and no. While my question applies to functions defined by the
> kernel, the same could apply to using a function provided by any package
> author writing expl3 code. For example, in my siunitx v3 code I'm hoping
> to provide
>
> \siunitx_units_format:nN { <input> } <token list>
>
> which might be taken up by another code author requiring
>
> \siunitx_units_format:VN
>
> So they would then have the question 'Do I document that I've created
> this publicly-usable function?' as well.
>
> Clearly, the two questions may have different answers as the generality
> of the kernel code doesn't necessarily apply to individual package authors.
I think the answer is the same (more or less). The only difference that
I would see is that while in the kernel we tried a fairly uniform set of
predefined variants I would thank that a package author has more freedom
deciding what he predefines.
Basically, if you as a package author define a certain base function as
being a public interface, say \siunitx_units_format:nN, then it is upto
you which variants you predefine (and also which of them you document).
However, the important point is that
- by defining the base function as an interface you have essentially
declared all variants as public (whether predefined or not)
- by documenting all the predefined ones all you do is that you save
any user of your package the burden to add a \cs_generate_variant:Nn
line to make them accessible
- and as a follow up you agree on supporting as being predefined
(i.e., that no \cs_generate_variant:Nn line is necessary for others to
use them).
If you if you use the variants yourself and you believe that this is not
going to change and the variants are generally useful, then I would
probably document them. However, documenting only a uniform set would
be equally defensible - neither really changes the usability of the
interface as *all* variants come implicitly into existence either way.
-------------------------------
>> Only the kernel itself is providing variants that all packages can and
>> should rely on. If certain variants are being needed (and therefore
>> generated) in many packages we may over time add them to the kernel so
>> that they become available by default and future packages have no need
>> to define them (but if they keep the \cs_generate_variant:Nn lines it
>> wouldn't hurt either).
>
> OK, so no documentation for using \cs_generate_variant:Nn alone: seems
> perfectly reasonable.
not for variants defined for interfaces of other packages or interfaces
of the kernel. This only generates dependencies that are unnecessary and
produce extra complications (then variants are available or not
depending on what other packages have been loaded and over time you get
surprises when you restructure code and take packages out).
frank
> --
> Joseph Wright
>
|
|
|