"Fossies" - the Fresh Open Source Software Archive

Member "mlmmj-1.3.0/README.listtexts" (2 Oct 2016, 21218 Bytes) of package /linux/privat/mlmmj-1.3.0.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README.listtexts": 1.2.19.0_vs_1.3.0.

    1 README.listtexts
    2 
    3 List texts in Mlmmj
    4 ===================
    5 
    6 List texts are stored in listdir/text and subdirectories of
    7 prefix/share/mlmmj/text.skel. They specify the content of various automatic
    8 emails that Mlmmj sends. They are provided in a number of different languages.
    9 The language to use for a list is chosen when you run the mlmmj-make-ml script
   10 and the appropriate files are copied into your listdir/text directory.
   11 
   12 This file documents the following aspects of list texts:
   13 
   14 - Naming scheme
   15 - Supported list texts
   16 - Format
   17 - Conditionals
   18 - Wrapping
   19 - Formatting and comments
   20 - Formatted substitutions
   21 - Unformatted substitutions
   22 - Escapes
   23 
   24 Naming scheme
   25 -------------
   26 
   27 List texts are named following a scheme of:
   28 
   29   purpose-action-reason-type
   30 
   31 Mlmmj will look for the full four-part name first, then for files with shorter
   32 names obtained by dropping parts off the end, and finally for a file with a
   33 compatibility filename. It will use the first one it finds. (Note that use of
   34 the compatibility filename is DEPRECATED and will be removed in a future
   35 release.)
   36 
   37 So, the complete search order is:
   38 
   39 - purpose-action-reason-type
   40 - purpose-action-reason
   41 - purpose-action
   42 - purpose
   43 - compatibility filename (DEPRECATED)
   44 
   45 When using shortened names, the %ifaction%, %ifreason%, %iftype% and related
   46 conditionals can be used to customise the list text according to the values of
   47 the missing parts.
   48 
   49 Mlmmj checks these three paths for each candidate filename, and then moves on
   50 to the next candidate filename:
   51 
   52 - listdir/text
   53 - prefix/share/mlmmj/text.skel/default
   54 - prefix/share/mlmmj/text.skel/en
   55 
   56 The second path does not exist by default, but can be created by copying or
   57 symlinking the language of your choice to that path.
   58 
   59 Note that this search order means that if there is a more specific list text in
   60 a system directory, it will override a less-specific or compatibility list text
   61 in the listdir. This may be surprising, and may change in a future version, so
   62 should not be relied upon. Best practice is to ensure each list has its own
   63 copy of all textx present in system directories, or none of them.
   64 
   65 Supported list texts
   66 --------------------
   67 
   68 The following list texts are supported. The compatibility filename (DEPRECATED)
   69 is given in brackets. Those with asterisks (*) are not yet used.
   70 
   71 - help (listhelp)
   72   sent in response to an email to listname+help@domain.tld
   73 
   74 - faq (listfaq)
   75   sent in response to an email to listname+faq@domain.tld
   76 
   77 - confirm-sub-{request|admin}-normal (sub-confirm)
   78 - confirm-sub-{request|admin}-digest (sub-confirm-digest)
   79 - confirm-sub-{request|admin}-nomail (sub-confirm-nomail)
   80 - confirm-unsub-{request|admin}-normal (unsub-confirm)
   81 - confirm-unsub-{request|admin}-digest (unsub-confirm-digest)
   82 - confirm-unsub-{request|admin}-nomail (unsub-confirm-nomail)
   83   sent to a requester to allow them to confirm a (un-)subscription request
   84 
   85 - moderate-post-{modnonsubposts|access|moderated} (moderation)
   86   sent to the appropriate moderators when moderation is required because a user
   87   has submitted a post
   88 
   89 - gatekeep-sub-{request|admin|confirm}-{normal|digest|nomail} (submod-moderator)
   90   sent to the appropriate gatekeepers when gatekeeping is required because a
   91   subscription request has been received
   92 
   93 - wait-post-{modnonsubposts|access|moderated} (moderation-poster)
   94   sent to a person submitting a post when they need to wait for moderation
   95   before it is released to the list
   96 
   97 - wait-sub-{request|admin|confirm}-{normal|digest|nomail} (submod-requester)
   98   sent to a person requesting subscription when they need to wait for
   99   gatekeeping for permission to join
  100 
  101 - deny-sub-disabled-{digest|both} (sub-deny-digest)
  102 - deny-sub-disabled-nomail (sub-deny-nomail)
  103 - deny-sub-subbed-{normal|digest|nomail|both} (sub-subscribed)
  104 - deny-sub-closed *
  105 - deny-sub-expired *
  106 - deny-sub-obstruct *
  107 - deny-unsub-unsubbed-{normal|digest|nomail|all} (unsub-notsubscribed)
  108 - deny-post-subonlypost (subonlypost)
  109 - deny-post-modonlypost
  110 - deny-post-access (access)
  111 - deny-post-maxmailsize (maxmailsize)
  112 - deny-post-tocc (notintocc)
  113 - deny-post-expired *
  114 - deny-post-reject *
  115 - deny-release-notfound *
  116 - deny-release-moderators *
  117 - deny-reject-notfound *
  118 - deny-reject-moderators *
  119 - deny-permit-notfound *
  120 - deny-permit-gatekeepers *
  121 - deny-obstruct-notfound *
  122 - deny-obstruct-gatekeepers *
  123   sent to the requestor when an action is denied or fails for some reason
  124   ('requestor' here means the person who requested the action, so e.g. for a
  125   reject action, deny-reject will go to the moderator requesting the rejection
  126   if the rejection fails; but deny-post-reject will go to the person requesting
  127   the post if the rejection succeeds, causing the post to fail)
  128 
  129 - finish-sub-{request|confirm|admin|permit|switch}-normal (sub-ok)
  130 - finish-sub-{request|confirm|admin|permit|switch}-digest (sub-ok-digest)
  131 - finish-sub-{request|confirm|admin|permit|switch}-nomail (sub-ok-nomail)
  132 - finish-unsub-{request|confirm|admin}-normal (unsub-ok)
  133 - finish-unsub-{request|confirm|admin}-digest (unsub-ok-digest)
  134 - finish-unsub-{request|confirm|admin}-nomail (unsub-ok-nomail)
  135 - finish-post-request *
  136 - finish-post-confirm *
  137 - finish-post-release *
  138 - finish-release *
  139 - finish-reject *
  140 - finish-permit *
  141 - finish-obstruct *
  142   sent to the requestor when an action completes successfully
  143   ('requestor' here means the person who requested the action, so e.g. for a
  144   release action, the moderator requesting the release will receive
  145   finish-release, and the person who submitted the released post will receive
  146   finish-post-release because the release action caused their post action to
  147   succeed)
  148 
  149 - notify-sub-{request|confirm|admin|permit}-normal (notifysub)
  150 - notify-sub-{request|confirm|admin|permit}-digest (notifysub-digest)
  151 - notify-sub-{request|confirm|admin|permit}-nomail (notifysub-nomail)
  152 - notify-unsub-{request|confirm|admin|bouncing}-normal (notifyunsub)
  153 - notify-unsub-{request|confirm|admin|bouncing}-digest (notifyunsub-digest)
  154 - notify-unsub-{request|confirm|admin|bouncing}-nomail (notifyunsub-nomail)
  155   sent to the list owner when somebody is (un-)subscribed
  156 
  157 - digest
  158   sent at the start of a digest (NOTE: the only header supported in this list
  159   text so far is a single-line 'Subject:' header; however, the contents of
  160   control/customheaders is included when digests are sent)
  161 
  162 - probe (bounce-probe)
  163   sent to a subscriber after an email to them bounced to inform them of the
  164   bounce and probe when the address is no longer bouncing
  165 
  166 - list---all (listsubs)
  167 - list---normal *
  168 - list---digest *
  169 - list---nomail *
  170   sent in response to an email to listname+list@domain.tld from the list owner
  171   (DEPRECATED: if none of %listsubs%, %digestsubs% and %nomailsubs% is
  172   encountered in the text, then they will be automatically added with some
  173   default formatting; this functionality is expected to be removed in the
  174   future)
  175 
  176 * Not yet used.
  177 
  178 Format
  179 ------
  180 
  181 List texts have the following format:
  182 
  183 - Headers
  184 - Blank line
  185 - Body
  186 
  187 They are expected to be in UTF-8 encoding and have Unix line endings.
  188 
  189 The headers should be formatted as they should appear in the mail message. They
  190 will begin the mail message. Header continuation via lines beginning with
  191 linear whitespace is supported.
  192 
  193 Following the headers found in the list text, Mlmmj will output the following
  194 default headers, unless the same header is already provided in the list text.
  195 
  196 - From:
  197 - To:
  198 - Message-ID:
  199 - Date:
  200 - Subject: mlmmj administrivia
  201 - MIME-Version: 1.0
  202 - Content-Type: text/plain; charset=utf-8
  203 - Content-Transfer-Encoding: 8bit
  204 
  205 The Subject: header is treated specially: it may include UTF-8 characters,
  206 which will automatically be escaped using the =?utf-8?q?...?= quoting
  207 mechanism.
  208 
  209 (NOTE: the 'digest' list text is a bit different. See its description above.)
  210 
  211 Both headers and bodies of list texts may include conditionals, formatting
  212 directives and substitutions. These are explained in the following sections.
  213  
  214 Conditionals
  215 ------------
  216 
  217 Conditionals allow text in list texts to be included or omitted based on
  218 conditions. The following are available:
  219 
  220 - %ifaction A ...%
  221   the action is one of those given
  222 
  223 - %ifreason R ...%
  224   the reason is one of those given
  225 
  226 - %iftype T ...%
  227   the type is one of those given
  228 
  229 - %ifcontrol C ...%
  230   one of the given control files exists
  231 
  232 - %ifnaction A%
  233   the action is not the one given
  234 
  235 - %ifnreason R%
  236   the reason is not the one given
  237 
  238 - %ifntype T%
  239   the type is not the one given
  240 
  241 - %ifncontrol C ...%
  242   at least one of the given control files does not exist
  243 
  244 The text after the %if...% directive is only included if the condition is
  245 satisfied, until an %else% or %endif% is encountered. These behave as you
  246 would expect. The %else% is optional.
  247 
  248 If a line with any of these conditional directives (%if...%, %else% or
  249 %endif%), after processing, contains only whitespace, the line does not appear
  250 at all in the output (the newline and any whitespace is omitted).
  251 
  252 Furthermore, if the preceding processed output ends with a blank line, when an
  253 unsatisfied conditional is encountered which has no %else% part, that
  254 preceding blank line is removed (unless it is the blank line that ends the
  255 headers).
  256 
  257 On the whole, this is what you would want and expect, so you probably don't
  258 need to worry about it.
  259 
  260 Note that when multiple parameters can be given for the directives, these have
  261 'or' behaviour; to get 'and' behaviour, nest conditionals.
  262 
  263 Wrapping
  264 --------
  265 
  266 There are various directives available to assist with wrapping and formatting.
  267 Wrapping needs to be enabled for each paragraph with:
  268 
  269 - %wrap%
  270 - %wrap W%
  271   concatenate and rewrap lines until the next empty line, whitespace-only line,
  272   or %nowrap% directive to a width of W (or 76 if W is omitted); second and
  273   later lines are preceded with as many spaces as the width preceding the
  274   directive; the width is reckoned including any text preceding the directive
  275   and any indentation preserved from a file which included the current one, so
  276   it is an absolute maximum width
  277 
  278 To turn off wrapping before the end of a paragraph, use:
  279 
  280 - %nowrap%
  281   stop wrapping; usually placed at the end of a line so the following line
  282   break is honoured but all preceding text is properly wrapped; if you want
  283   wrapping to continue after the break, you need to use %wrap% to turn it on
  284   again on the following line
  285 
  286 To cater for various languages, there are a number of different wrapping modes
  287 that can be set. These can be set either before or after wrapping is specified,
  288 and can even be changed part way through a paragraph if desired. The following
  289 directives control them:
  290 
  291 - %wordwrap%
  292 - %ww%
  293   use word-wrapping (this is the default; good for English, French, Greek and
  294   other languages that use an alphabet and spaces between words); lines have
  295   whitespace trimmed from both ends and are joined with a single space; lines
  296   are broken at spaces or at points marked for breaking with \/, but not at
  297   spaces escaped with a backslash
  298 
  299 - %charwrap%
  300 - %cw%
  301   use character-wrapping (good for Chinese, Japanese and Korean which use
  302   characters without spaces between words); lines have only leading whitespace
  303   trimmed and are joined without inserting anything at the joint; lines are
  304   broken at space or any non-ASCII character except where disallowed with \=
  305 
  306 - %userwrap%
  307 - %uw%
  308   use user-wrapping (for more complex languages or wherever complete manual
  309   control is desired); lines have only leading whitespace trimmed and are
  310   joined without inserting anything at the joint; lines are broken only where
  311   marked for breaking with \/
  312 
  313 - %thin%
  314   assume non-ASCII characters are thin (equivalent to one unit, the same as
  315   ASCII characters) when reckoning the width for wrapping (this is the default;
  316   good for languages like Greek which use a non-Latin alphabet)
  317 
  318 - %wide%
  319   assume non-ASCII characters are wide (equivalent to two units, twice as wide
  320   as ASCII characters) when reckoning the width for wrapping (good for Chinese,
  321   Japanese, Korean)
  322 
  323 - %zero ABC%
  324   (ABC represents a sequence of non-ASCII characters)
  325   treat the listed characters as having zero-width when reckoning the width for
  326   wrapping (useful for ignoring combining characters such as accents so they
  327   don't affect the width calculation); usefully, the listed characters can be
  328   represented as unicode escapes (\uNNNN)
  329 
  330 If a line with any of the directives in this section, after processing,
  331 contains only whitespace, the line does not appear at all in the output (the
  332 newline and any whitespace is omitted).
  333 
  334 Formatting and comments
  335 -----------------------
  336 
  337 The following directives are available to assist with formatting and
  338 readability:
  339 
  340 - %^%
  341   start the line here; anything preceding this directive is ignored (useful for
  342   using indentation for readability without ruining the formatting of the text
  343   when it is processed)
  344 
  345 - %comment%
  346 - %$%
  347   end the line here; anything following this directive is ignored/a comment
  348 
  349 If a line with any of these directives, after processing, contains only
  350 whitespace, the line does not appear at all in the output (the newline and any
  351 whitespace is omitted).
  352 
  353 Formatted substitutions
  354 -----------------------
  355 
  356 These formatted substitutions work with multiple lines, so are generally not
  357 appropriate for use in headers. They are:
  358 
  359 - %text T%
  360   text from the file named T in the listdir/text directory; the name may only
  361   include letters, digits, underscore, dot and hyphen, and may not start with a
  362   dot; note that there is an unformatted version of this directive
  363 
  364 - %control C%
  365   the contents of the control file named C in listir/control; the name may only
  366   include letters, digits, underscore, dot and hyphen, and may not start with a
  367   dot; note that there is an unformatted version of this directive
  368 
  369 - %originalmail%
  370 - %originalmail N%
  371   (available only in moderate-post-*, wait-post-* and
  372   deny-post-{access|maxmailsize|tocc|subonlypost|modonlypost})
  373   the email message being processed (usually a mail being moderated); N
  374   represents a number, which is how many lines of the message (including
  375   headers) to include: if omitted, the whole message will be included
  376 
  377 - %digestthreads%
  378   (available only in digest)
  379   the list of threads included in the digest
  380 
  381 - %gatekeepers%
  382   (available only in gatekeep-sub and wait-sub)
  383   the list of moderators to whom the moderation request has been sent
  384 
  385 - %listsubs%
  386   (available only in list---*)
  387   the list of normal subscribers
  388   DEPRECATED: use %normalsubs%
  389 
  390 - %normalsubs%
  391   (available only in list---*)
  392   the list of normal subscribers
  393 
  394 - %digestsubs%
  395   (available only in list---*)
  396   the list of digest subscribers
  397 
  398 - %nomailsubs%
  399   (available only in list---*)
  400   the list of nomail subscribers
  401 
  402 - %moderators%
  403   (available only in moderate-post-* and wait-post-*)
  404   the list of moderators to whom the moderation request has been sent
  405 
  406 - %bouncenumbers%
  407   (available only in probe)
  408   the list of indexes of messages which may not have been received as they
  409   bounced
  410 
  411 Directives which include a list of items have the behaviour that each item is
  412 preceded and followed by the same text as preceded and followed the directive
  413 on its line; only one such directive is supported per line. Those which include
  414 a block of text have the behaviour that second and later lines are preceded
  415 with as many spaces as there were bytes preceding the directive; any text
  416 following such directives on the same line is omitted.
  417 
  418 If a line with any of these directives, after processing, contains only
  419 whitespace, the line does not appear at all in the output (the newline and any
  420 whitespace is omitted).
  421 
  422 Unformatted substitutions
  423 -------------------------
  424 
  425 Unformatted substitutions that are available are:
  426 
  427 - $bouncenumbers$
  428   (available only in probe)
  429   the formatted list of indexes of messages which may not have been received as
  430   they bounced
  431   DEPRECATED: use %bouncenumbers%
  432 
  433 - $confaddr$
  434 - $confirmaddr$
  435   (available only in confirm-[un]sub-*)
  436   the address to which to send mail to confirm the (un-)subscription in
  437   question
  438   NOTE: the short version of this substitution is DEPRECATED
  439 
  440 - $control C$
  441   the contents of the control file named C in listdir/control, with its final
  442   newline stripped; the name may only include letters, digits, underscore, dot
  443   and hyphen, and may not start with a dot; note that there is a formatted
  444   version of this directive
  445 
  446 - $digestfirst$
  447   (available only in digest)
  448   index of the first message included in a digest
  449 
  450 - $digestinterval$
  451   (available only in digest)
  452   indexes of the first and last messages included in a digest (e.g. 1-5), or
  453   just the index if only a single message is included
  454 
  455 - $digestissue$
  456   (available only in digest)
  457   the issue number of the digest
  458 
  459 - $digestlast$
  460   (available only in digest)
  461   index of the last message included in a digest
  462 
  463 - $digestsubaddr$
  464   listname+subscribe-digest@domain.tld
  465   DEPRECATED: use $list+$subscribe-digest@$domain$ instead
  466 
  467 - $digestthreads$
  468   (available only in digest)
  469   the formatted list of threads included in the digest
  470   DEPRECATED: use %digestthreads%
  471 
  472 - $digestunsubaddr$
  473   listname+unsubscribe-digest@domain.tld
  474   DEPRECATED: use $list+$unsubscribe-digest@$domain$ instead
  475 
  476 - $domain$
  477   domain.tld
  478 
  479 - $faqaddr$
  480   listname+faq@domain.tld
  481   DEPRECATED: use $list+$faq@$domain$ instead
  482 
  483 - $helpaddr$
  484   listname+help@domain.tld
  485   DEPRECATED: use $list+$help@$domain$ instead
  486 
  487 - $list$
  488   listname
  489 
  490 - $list+$
  491   listname+
  492 
  493 - $listaddr$
  494   listname@domain.tld
  495   DEPRECATED: use $list$@$domain$ instead
  496 
  497 - $listgetN$
  498   listname+get-N@domain.tld
  499   (the N here is nothing special, so this won't actually work, but is used to
  500   explain to users how to use the +get functionality)
  501   DEPRECATED: use $list+$get-N@$domain$ instead
  502 
  503 - $listowner$
  504   listname+owner@domain.tld
  505   DEPRECATED: use $list+$owner@$domain$ instead
  506 
  507 - $listsubaddr$
  508   listname+subscribe@domain.tld
  509   DEPRECATED: use $list+$subscribe@$domain$ instead
  510 
  511 - $listunsubaddr$
  512   listname+unsubscribe@domain.tld
  513   DEPRECATED: use $list+$unsubscribe@$domain$ instead
  514 
  515 - $maxmailsize$
  516   (available only in deny-post-maxmailsize)
  517   the maximum size of mail that Mlmmj will accept
  518 
  519 - $moderateaddr$
  520   (available only in moderate-post-* and gatekeep-sub)
  521   the address to which to send mail to approve the post or subscription in
  522   question
  523   DEPRECATED: use $releaseaddr$ or $permitaddr$ instead
  524 
  525 - $moderators$
  526   (available only in moderate-post-*, wait-post-*, gatekeep-sub and wait-sub)
  527   the formatted list of moderators to whom the moderation request has been sent
  528   DEPRECATED: use %moderators% or %gatekeepers% instead
  529 
  530 - $newsub$
  531   (available only in notify-sub-*-*)
  532   the address that has been subscribed
  533   DEPRECATED: use $subaddr$ instead
  534 
  535 - $nomailsubaddr$
  536   listname+subscribe-nomail@domain.tld
  537   DEPRECATED: use $list+$subscribe-nomail@$domain$ instead
  538 
  539 - $nomailunsubaddr$
  540   listname+unsubscribe-nomail@domain.tld
  541   DEPRECATED: use $list+$unsubscribe-nomail@$domain$ instead
  542 
  543 - $oldsub$
  544   (available only in notify-sub-*-*)
  545   the address that has been unsubscribed
  546   DEPRECATED: use $subaddr$ instead
  547 
  548 - $originalmail$
  549   the same as %originalmail 100% preceded by a space
  550   DEPRECATED: use %originalmail%
  551 
  552 - $permitaddr$
  553   (available only in gatekeep-sub)
  554   the address to which to send mail to permit the subscription in question
  555 
  556 - $posteraddr$
  557   (available only in deny-post-{access|tocc|subonlypost|modonlypost|
  558   maxmailsize}, moderate-post-* and wait-post-*)
  559   the from address of the message that was received as determined by Mlmmj
  560 
  561 - $random0$
  562 - $random1$
  563 - $random2$
  564 - $random3$
  565 - $random4$
  566 - $random5$
  567   these are 6 distinct random strings; they allow list texts to be constructed
  568   that are MIME messages with attachments by creating boundaries that are
  569   unlikely to appear in the attached messages
  570 
  571 - $releaseaddr$
  572   (available only in moderate-post-*)
  573   the address to which to send mail to release the post in question
  574 
  575 - $subaddr$
  576   (available only in gatekeep-sub, confirm-[un]sub-*, finish-[un]sub-*,
  577   notify-[un]sub-* and deny-[un]sub-*)
  578   the address requested to be (un-)subscribed
  579 
  580 - $subject$
  581   (available only in deny-post-{access|tocc|subonlypost|modonlypost|
  582   maxmailsize}, moderate-post-* and wait-post-*)
  583   the subject line of the message in question
  584 
  585 - $text T$
  586   text from the file named T in the listdir/text directory, with its final
  587   newline stripped; the name may only include letters, digits, underscore, dot
  588   and hyphen, and may not start with a dot; note that there is a formatted
  589   version of this directive
  590 
  591 Escapes
  592 -------
  593 
  594 These allow you to avoid special meanings of characters used for other purposes
  595 in list texts, as well as control the construction of the texts at a fairly low
  596 level.
  597 
  598 - $$
  599   a single $
  600 
  601 - %%
  602   a single %
  603 
  604 - \\
  605   a single \
  606 
  607 - \uNNNN
  608   (NNNN represents four hex digits)
  609   a Unicode character
  610   (this is not really appropriate for use in a header, except perhaps the
  611   Subject: header as Mlmmj does automatic quoting for that header as described
  612   above)
  613 
  614 - \<space>
  615   a space, but don't allow the line to be broken here when wrapping
  616 
  617 - \/
  618   nothing, but allow the line to be broken here when wrapping
  619 
  620 - \=
  621   nothing, but don't allow the line to be broken here when wrapping
  622