[latex3-commits] [l3svn] r6919 - Document one use of flags, insist not to use flags

[noreply at latex-project.org]

Author: bruno
Date: 2017-02-14 00:51:34 +0100 (Tue, 14 Feb 2017)
New Revision: 6919

Modified:
   trunk/l3experimental/l3str/l3flag.dtx
Log:
Document one use of flags, insist not to use flags


Modified: trunk/l3experimental/l3str/l3flag.dtx
===================================================================
--- trunk/l3experimental/l3str/l3flag.dtx	2017-02-13 23:43:01 UTC (rev 6918)
+++ trunk/l3experimental/l3str/l3flag.dtx	2017-02-13 23:51:34 UTC (rev 6919)
@@ -86,6 +86,18 @@
 % part of \cs{use:c} constructions hence is expanded at point of use.
 % It must expand to character tokens only, with no spaces.
 %
+% A typical use case of flags would be to keep track of whether an
+% exceptional condition has occured during expandable processing, and
+% produce a meaningful (non-expandable) message after the end of the
+% expandable processing.  This is exemplified by \pkg{l3str-convert},
+% which for performance reasons performs conversions of individual
+% characters expandably and for readability reasons produces a single
+% error message describing incorrect inputs that were encountered.
+%
+% Flags should not be used without carefully considering the fact that
+% raising a flag takes a time and memory proportional to its height.
+% Flags should not be used unless unavoidable.
+%
 % \section{Setting up flags}
 %
 % \begin{function}{\flag_new:n}