summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/mfirstuc/mfirstuc-manual.tex
blob: c53b166eb4104c95fb2845a202c608acd466532b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
% arara: lualatex
% arara: bib2gls: { group: on, options: [ "--replace-quotes" ] }
% arara: lualatex
% arara: bib2gls: { group: on, options: [ "--replace-quotes" ] } if found ("log", "Glossary entry `sym.")
% arara: lualatex
% arara: lualatex if found ("log", "Rerun to")

% This document requires glossaries-extra v1.49, bib2gls v3.0
% and nlctuserguide.sty. If they haven't already 
% been uploaded to CTAN, they will be in a few days.

\documentclass[titlepage=false,oneside,
 fontsize=12pt,captions=tableheading]{scrbook}

\usepackage
 %[debug=showwrgloss]
 {nlctuserguide}

\nlctuserguidegls
{
  % \MFUsentencecase
  \gcmd{MFU\-sen\-tence\-case}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{text}}%
    \desc{converts \meta{text} to \idx+{sentence-case} with expansion}
  }
  % \MFUexcl
  \gcmd{MFU\-excl}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{cs}}%
    \desc{locally identifies \meta{cs} as an \idx{exclusion} command}
    \field{seealso}{MFUblocker,MFUaddmap}
  }
  % \MFUblocker
  \gcmd{MFU\-blocker}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{cs}}%
    \desc{locally identifies \meta{cs} as a \idx{blocker} command}
    \field{seealso}{MFUexcl,MFUaddmap}
  }
  % \MFUaddmap
  \gcmd{MFU\-add\-map}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{cs1}\margm{cs2}}%
    \desc{identifies a \idx{mapping} from the command \meta{cs1} to
    command \meta{cs2}}
    \field{seealso}{MFUexcl,MFUblocker}
  }
  % \MFUsaveatend
  \gcmd{MFU\-save\-at\-end}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \desc{saves the list of \idxpl{exclusion}, \idxpl{blocker}
     and \idxpl{mapping} to the \ext{aux} file (if required by some
     external tool) at the end of the document. 
     This command sets itself to \cmd{relax} so it
     doesn't repeat the action if used multiple times, but it can
     be overridden by \gls{MFUsave}}
  }
  % \MFUsave
  \gcmd{MFU\-save}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \desc{saves the list of \idxpl{exclusion}, \idxpl{blocker}
     and \idxpl{mapping} to the \ext{aux} file (if required by some
     external tool). 
     This command sets itself to \cmd{relax} so it
     doesn't repeat the action if used multiple times, and
     counteracts any use of \gls{MFUsaveatend}}
  }
  % \@mfu@excls
  \gcmd{@mfu\-@\-excls}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{exclusions}}
    \desc{an \ext{aux} file command that lists all the identified
    \idxpl{exclusion}}
    \field{seealso}{MFUsave,MFUsaveatend}
  }
  % \@mfu@blockers
  \gcmd{@mfu\-@\-blockers}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{blockers}}
    \desc{an \ext{aux} file command that lists all the identified
    \idxpl{blocker}}
    \field{seealso}{MFUsave,MFUsaveatend}
  }
  % \@mfu@mappings
  \gcmd{@mfu\-@\-mappings}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{mappings}}
    \desc{an \ext{aux} file command that lists all the identified
    \idxpl{mapping} as a \keyval\ list}
    \field{seealso}{MFUsave,MFUsaveatend}
  }
  % \mfirstucMakeUppercase
  \gcmd{mfirst\-uc\-Make\-Up\-per\-case}
  {
    \providedby{\sty{mfirstuc} v1.07+}
    \syntax{\margm{text}}%
    \desc{converts \meta{text} to \idx{uppercase}. 
     Now only used in \gls{mfugrabfirstuc}}
  }
  % \emakefirstuc
  \gcmd{e\-make\-first\-uc}
  {
    \providedby{\sty{mfirstuc} v1.10+}
    \syntax{\margm{text}}%
    \desc{fully expands \meta{text} before passing it to
    \gls{makefirstuc}}
  }
  % \xmakefirstuc
  \gcmd{x\-make\-first\-uc}
  {
    \providedby{\sty{mfirstuc} v1.01+}
    \syntax{\margm{text}}%
    \desc{shortcut for
     \code{\cmd{expandafter}\gls{makefirstuc}\cmd{expandafter}\margm{text}}}
  }
  % \makefirstuc
  \gcmd{make\-first\-uc}
  {
    \providedby{\sty{mfirstuc} v1.0+}
    \syntax{\margm{text}}%
    \desc{converts \meta{text} to \idx+{sentence-case} internally using
    \gls{glsmakefirstuc} to perform the case-change, but first parses
    \meta{text} to deal with special cases}
  }
  % \glsmakefirstuc
  \gcmd{gls\-make\-first\-uc}
  {
    \providedby{\sty{mfirstuc} v1.05+}
    \syntax{\margm{text}}%
    \desc{used by \gls{makefirstuc} to perform the case-change. This
    uses \code{\gls{MFUsentencecase}\margm{text}} but by default
    will prevent its argument from being expanded}
  }
  % \mfugrabfirstuc
  \gcmd{mfu\-grab\-first\-uc}
  {
    \providedby{\sty{mfirstuc} v2.08+}
    \syntax{\margm{text}}
    \note{avoid where possible}
    \desc{provide to emulate \gls{glsmakefirstuc} in v2.07 and
    below, but can still produce different results to v2.07.
    This will attempt to grab only the first character of
    \meta{text} and convert it to \idx{uppercase}, leaving the rest of
    \meta{text} unchanged. This won't work if \meta{text} starts
    with a \gls{utf8} character, unless you are using \XeLaTeX\ or
    \LuaLaTeX}
  }
  % \MFUskippunc
  \gcmd{MFU\-skip\-punc}
  {
    \providedby{\sty{mfirstuc} v2.07+}
    \syntax{\margm{content}}%
    \desc{an \idx{exclusion} command}
  }
  % \capitalisewords
  \gcmd{cap\-i\-talise\-words}
  {
    \providedby{\sty{mfirstuc} v1.06+}
    \syntax{\margm{text}}%
    \desc{applies \idx+{title-case} to \meta{text}. This will apply 
    \gls{MFUcapword} to each word in \meta{text} (unless the word has been
    identified as an \idx{exclusion-word} and doesn't occur at the start of
    \meta{text})}
    \field{seealso}{capitalisefmtwords,MFUnocap,gMFUnocap,ifMFUhyphen}
  }
  % \xcapitalisewords
  \gcmd{x\-cap\-i\-talise\-words}
  {
    \providedby{\sty{mfirstuc} v1.06+}
    \syntax{\margm{text}}%
    \desc{shortcut for
     \code{\cmd{expandafter}\gls{capitalisewords}\cmd{expandafter}\margm{text}}}
  }
  % \ecapitalisewords
  \gcmd{e\-cap\-i\-talise\-words}
  {
    \providedby{\sty{mfirstuc} v1.10+}
    \syntax{\margm{text}}%
    \desc{fully expands \meta{text} before passing it to \gls{capitalisewords}}
  }
  % \capitalisefmtwords
  \gcmd{cap\-i\-talise\-fmt\-words}
  {
    \providedby{\sty{mfirstuc} v2.03+}
    \syntax{\margm{text}}%
    \desc{similar to \gls{capitalisewords} but for content that may
    contain formatting commands}
    \field{modifiers}{*}
    \field{seealso}{capitalisewords,MFUnocap,gMFUnocap,ifMFUhyphen}
  }
  % \xcapitalisefmtwords
  \gcmd{x\-cap\-i\-talise\-fmt\-words}
  {
    \providedby{\sty{mfirstuc} v2.03+}
    \syntax{\margm{text}}%
    \desc{shortcut for
     \code{\cmd{expandafter}\gls{capitalisefmtwords}\cmd{expandafter}\margm{text}}
     including the \code{*} modifier, if provided}
    \field{modifiers}{*}
  }
  % \ecapitalisefmtwords
  \gcmd{e\-cap\-i\-talise\-fmt\-words}
  {
    \providedby{\sty{mfirstuc} v2.03+}
    \syntax{\margm{text}}%
    \desc{fully expands \meta{text} and passes it to
      \gls{capitalisefmtwords} including the \code{*} modifier, if provided}
    \field{modifiers}{*}
  }
  % \ifMFUhyphen
  \gcond{if\-MFU\-hyphen}
  {
    \initval{\cmd{iffalse}}
    \providedby{\sty{mfirstuc} v2.03+}
    \desc{conditional that determines whether or not hyphens should
    be considered word boundaries by the \idx{title-case} commands}
  }
  % \MFUhyphentrue
  \gcmd{MFU\-hyphen\-true}
  {
    \providedby{\sty{mfirstuc} v2.03+}
    \desc{sets \gls{ifMFUhyphen} to true}
  }
  % \MFUhyphenfalse
  \gcmd{MFU\-hyphen\-false}
  {
    \providedby{\sty{mfirstuc} v2.03+}
    \desc{sets \gls{ifMFUhyphen} to false}
  }
  % \MFUwordbreak
  \gcmd{MFU\-word\-break}
  {
    \providedby{\sty{mfirstuc} v2.07+}
    \syntax{\margm{text}}%
    \desc{used to markup a character or command that should be
    treated as a word break by the \idx{title-case} commands}
  }
  % \MFUcapword
  \gcmd{MFU\-cap\-word}
  {
    \providedby{\sty{mfirstuc} v2.03+}
    \syntax{\margm{text}}%
    \desc{uses either \gls{MFUhyphencapword} or \gls{MFUcapwordfirstuc}
     depending on \gls{ifMFUhyphen}}
  }
  % \MFUcapwordfirstuc
  \gcmd{MFU\-cap\-word\-first\-uc}
  {
    \providedby{\sty{mfirstuc} v2.07+}
    \syntax{\margm{word}}%
    \desc{used by \gls{MFUcapword} and \gls{MFUhyphencapword} to 
    apply the case-change to the given word. This just does 
    \code{\gls{makefirstuc}\margm{text}} by default}
    \field{seealso}{MFUcapword,MFUhyphencapword}
  }
  % \MFUhyphencapword
  \gcmd{MFU\-hyphen\-cap\-word}
  {
    \providedby{\sty{mfirstuc} v2.07+}
    \syntax{\margm{text}}%
    \desc{used by \gls{MFUcapword} to apply \gls{MFUcapwordfirstuc} to 
    each hyphen-separated word in \meta{text}, if hyphens should
    indicate a word-break}
    \field{seealso}{ifMFUhyphen,MFUcapword}
  }
  % \MFUnocap
  \gcmd{MFU\-no\-cap}
  {
    \providedby{\sty{mfirstuc} v1.09+}
    \syntax{\margm{word}}%
    \desc{locally adds \meta{word} to the \idx{exclusion-word} list for
    \gls{capitalisewords}}
    \field{seealso}{gMFUnocap,MFUclear}
  }
  % \gMFUnocap
  \gcmd{gMFU\-no\-cap}
  {
    \providedby{\sty{mfirstuc} v1.09+}
    \syntax{\margm{word}}%
    \desc{globally adds \meta{word} to the \idx{exclusion-word} list for
    \gls{capitalisewords}}
    \field{seealso}{MFUnocap,MFUclear}
  }
  % \MFUclear
  \gcmd{MFU\-clear}
  {
    \providedby{\sty{mfirstuc} v1.09+}
    \desc{locally clears the \idx{exclusion-word} list for \gls{capitalisewords}}
    \field{seealso}{gMFUnocap,MFUnocap}
  }
  % PACKAGE OPTIONS
  % option grabfirst
  \gopt{grab\-first}
  {%
    \providedby{\sty{mfirstuc} v2.08+}
    \note{avoid where possible}
    \desc{redefines \gls{glsmakefirstuc} to use \gls{mfugrabfirstuc}
     and \gls{mfirstucMakeUppercase} to use \gls{MakeUppercase}}
  }
  % option expanded
  \gopt{expanded}
  {%
    \providedby{\sty{mfirstuc} v2.08+}
    \desc{redefines \gls{glsmakefirstuc} to use \gls{MFUsentencecase}
      without inhibiting the expansion of its argument}
  }
  % option unexpanded
  \gopt{unexpanded}
  {%
    \providedby{\sty{mfirstuc} v2.08+}
    \desc{redefines \gls{glsmakefirstuc} to use \gls{MFUsentencecase}
      but inhibits expansion of its argument}
  }
  % COMMANDS: index only
  \gcmd{text\dsb title\-case\dsb first:n}{}
  \gcmd{text\dsb title\-case:n}{}
  \gcmd{text\dsb upper\-case:n}{}
  \gcmd{l\dsb text\dsb case\dsb ex\-clude\dsb arg\dsb tl}{}
  \gcmd{protect}{}
  \gcmd{unexpanded}{}
  \gcmd{glsadd}{}
  \gcmd{gls}{}
  \gcmd{Gls}{}
  \gcmd{GLS}{}
  \gcmd{glspl}{}
  \gcmd{Glspl}{}
  \gcmd{GLSpl}{}
  \gcmd{Make\-Upper\-case}{}% \MakeUppercase
  \gcmd{Make\-Text\-Upper\-case}{}% \MakeTextUppercase
  \gcmd{No\-Case\-Change}{}% \NoCaseChange
  \gcmd{ensure\-math}{}
  \gcmd{begin}{}
  \gcmd{end}{}
  \gcmd{cite}{}
  \gcmd{label}{}
  \gcmd{ref}{}
  \gcmd{index}{}
  \gcmd{space}{}
  \gcmd{name\-ref}{}% \nameref
  \gcmd{tex\-or\-pdf\-string}{}% \texorpdfstring
  \gcmd{pdf\-string\-def\-Dis\-able\-Commands}{}% \pdfstringdefDisableCommands
  \gpunc{nbsp}{\name{\code{\textasciitilde}}}% ~
  % packages
  \gpkg{mfirst\-uc}{\common}
  \gpkg{mfirstuc\dhyphen english}{}
  \gpkg{glossaries}{}
  \gpkg{glossaries\dhyphen extra}{}
  \gpkg{text\-case}{}% textcase
  \gpkg{cs\-quotes}{}% csquotes
  \gpkg{hyper\-ref}{}% hyperref
  % file extensions
  \gext{aux}{}
  % terms
  \gterm{exclusion}{\name{exclusion command}\field{text}{exclusion}
  \desc{a command whose argument should be skipped
  by the case-changer. The content that follows the command should
  have its case-changed instead. See \sectionref{sec:exclusions}}}
  \gterm{blocker}{\desc{a command that prohibits case-changing. If
   encountered by \gls{makefirstuc}, it won't attempt to apply any
   case-changing. See \sectionref{sec:blockers}}}
  \gterm{mapping}{\desc{a command that should be substituted by
   another, if encountered by \gls{makefirstuc}, instead of applying
   a case-change. See \sectionref{sec:mappings}}}
  \gterm{sentence-case}{\desc{content that should appear at the
   start of a sentence that needs to have its first significant
   character converted to \idx{uppercase}. See \sectionref{sec:sentencecase}}}
  \gterm{title-case}{\desc{content that needs to appear in a title
   that should have each significant word converted to
   \idx{sentence-case}. See \sectionref{sec:capitalisewords}}}
  \gterm{exclusion-word}{\name{exclusion word}
   \desc{a word that shouldn't have its case changed by
   \idx{title-case} commands, unless the word occurs at the start}}
  \gtermacr{utf8}{UTF-8}{Unicode Transformation Format (8-bit)}
  {%
    \desc{a variable-width encoding that uses 8-bit code units. This
    means that some characters are represented by more that one byte.
    \XeLaTeX\ and \LuaLaTeX\ treat the multi-byte sequence as a single
    token, but the older \LaTeX\ formats have single-byte tokens, which
    can cause complications, although these have mostly been addressed with
    the newer kernels introduced over the past few years. Related blog article:
    \blog{binary-files-text-files-and-file-encodings/}{Binary Files,
    Text Files and File Encodings}}
  }
  \gterm{semanticcommand}{\name{semantic command}
    \desc{essentially, this is a command associated with a
    particular element, idea or topic that hides the font
    and other stylistic formatting inside its definition. For
    example, Latin taxonomy is usually displayed in italic.
    Explicitly using font commands, for example
    \begin{compactcodebox}\cmd{textit}\marg{Clostridium}\end{compactcodebox}
    is syntactic markup.
    Whereas defining a command called, say, \cmd{bacteria} that 
    displays its argument in italics is a semantic command. The
    actual styling is hidden and the command relates specifically to
    a particular concept.
\begin{codebox}
Syntactic: \cmd{textit}\marg{Clostridium}^^J\codepar
\cmd{newrobustcmd}*\marg{\cmd{bacteria}}[1]{\cmd{emph}\marg{\#1}}\%\newline
Semantic: \cmd{bacteria}\marg{Clostridium}
\end{codebox}
    The end result is the same: 
\begin{resultbox}
Syntactic: \textit{Clostridium}\glspar
Semantic: \emph{Clostridium}
\end{resultbox}
    The advantage with semantic commands is that it's much easier to
    change the style, simply by adjusting the command definition.
    Note that I've used \cmd{newrobustcmd} to make the semantic
    command robust as the style commands can cause a problem if they
    expand too soon}
  }
  % index only
  \gidx{punctuation}{}
  \gpunc{sym.dollar}{\name{\code{\$}}}% $
  \gidx{uppercase}{}
  \gidx{lowercase}{}
}

\title{mfirstuc.sty v2.08: 
sentence and title casing}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}}
\date{2022-10-14
}

\begin{document}
\maketitle

\htmlavailable

\begin{information}
The \sty{mfirstuc} package was originally part of the
\sty{glossaries} bundle (added to \sty{glossaries} v1.12 
in 2008) for use with commands like \gls{Gls},
which need to have the first letter converted to uppercase
(\idx{sentence-case}), but as the commands provided by 
\sty{mfirstuc} may be used without \sty{glossaries}, the two 
were split into separately maintained packages in 2015
(\sty{mfirstuc} v2.0 and \sty{glossaries} v4.18).
\end{information}

Version 2.08 has reimplemented \gls{makefirstuc} using \LaTeX3
commands. If there are any compatibility issues, you can rollback to
v2.07:
\begin{codebox}
\cmd{usepackage}\marg{mfirstuc}[=2.07]
\end{codebox}

\frontmatter
\tableofcontents

\mainmatter
\chapter{Sentence-Case}
\label{sec:sentencecase}

There are two \idx{sentence-case} commands provided: \gls{MFUsentencecase}
and \gls{makefirstuc}. A summary of the principle features of 
the two commands is given in
\tableref{tab:sentencecasesummary}.

\begin{table}[htbp]
\caption{Principle features of
\glsfmttext{MFUsentencecase} and \glsfmttext{makefirstuc}}
\label{tab:sentencecasesummary}
\centering
\begin{tabular}{lcc}
\bfseries Feature & \bfseries \gls{MFUsentencecase}[]
& \bfseries \gls{makefirstuc}[]\\
Can expand? & \proyes & \prono\\
Supports \idxpl{exclusion}? & \proyes & \proyes\\
Supports \idxpl{blocker}? & \prono & \proyes\\
Supports \idxpl{mapping}? & \prono & \proyes\\
Semantic commands must be robust? & \conyes & \conno
\end{tabular}
\end{table}

\section{Examples}
\label{sec:sentencecaseex}

Text only (leading \idx{utf8} now supported):
\begin{coderesult}
\gls{makefirstuc}\marg{élite} /
\gls{MFUsentencecase}\marg{élite}
\tcblower
\makefirstuc{élite} /
\MFUsentencecase{élite}
\end{coderesult}

Leading \idx{punctuation} is ignored:
\begin{coderesult}
\gls{makefirstuc}\marg{`word'} /
\gls{MFUsentencecase}\marg{`word'}
\tcblower
\makefirstuc{`word'} /
\MFUsentencecase{`word'}
\end{coderesult}
However, if the \idx{punctuation} character is followed by a
\idx{blocker} or \idx{mapping} command, the \idx{punctuation} will
need to be excluded otherwise the command will be treated as an
\idx{exclusion}. If possible, use \idxc{semanticcommand}{semantic
markup} instead of directly including the \idx{punctuation}.

Fragile commands need to be protected with
\gls{MFUsentencecase}:
\begin{codebox}
\cmd{newcommand}\marg{\cmd{alert}}[1]\marg{\cmd{textcolor}\marg{red}\marg{\cmd{textbf}\marg{\#1}}}
\gls{makefirstuc}\marg{\cmd{alert}\marg{élite}} /
\gls{MFUsentencecase}\marg{\strong{\cmd{protect}}\cmd{alert}\marg{élite}}
\end{codebox}
\begin{resultbox}
\newcommand{\alert}[1]{\textcolor{red}{\textbf{#1}}}
\makefirstuc{\alert{élite}} /
\MFUsentencecase{\protect\alert{élite}}
\end{resultbox}

\Idxpl{exclusion} are supported by both \gls{makefirstuc} and
\gls{MFUsentencecase}:
\begin{codebox}
\gls{MFUexcl}\marg{\gls+{index}}
\gls{makefirstuc}\marg{\gls{index}\marg{word}example} /
\gls{MFUsentencecase}\marg{\gls{index}\marg{word}example}
\end{codebox}
\begin{resultbox}
\MFUexcl{\index}
\makefirstuc{\index{example}example} /
\MFUsentencecase{\index{example}example}
\end{resultbox}

\Idxpl{blocker} are only supported by \gls{makefirstuc}. 
They are treated as \idxpl{exclusion} with
\gls{MFUsentencecase}, which produces a different result:
\begin{codebox}
\gls{MFUblocker}\marg{\gls+{nameref}}
\gls{makefirstuc}\marg{\gls{nameref}\marg{sec:sentencecase} section} /
\gls{MFUsentencecase}\marg{\gls{nameref}\marg{sec:sentencecase} section}
\end{codebox}
\begin{resultbox}
\MFUblocker{\nameref}
\makefirstuc{\nameref{sec:sentencecase} section} /
\MFUsentencecase{\nameref{sec:sentencecase} section}
\end{resultbox}

\Idxpl{mapping} are only supported by \gls{makefirstuc}.
They are treated as \idxpl{exclusion} with
\gls{MFUsentencecase}, which produces a different result:
\begin{codebox}
\cmd{newrobustcmd}\marg{\cmd{secref}}[1]\marg{section\glstildechar\cmd{ref}\marg{\#1}}
\cmd{newrobustcmd}\marg{\cmd{Secref}}[1]\marg{Section\glstildechar\cmd{ref}\marg{\#1}}
\gls{MFUaddmap}\marg{\cmd{secref}}\marg{\cmd{Secref}}
\gls{makefirstuc}\marg{\cmd{secref}\marg{sec:sentencecase} example} /
\gls{MFUsentencecase}\marg{\cmd{secref}\marg{sec:sentencecase} example}
\end{codebox}
\begin{resultbox}
\newrobustcmd{\secref}[1]{section~\ref{#1}}
\newrobustcmd{\Secref}[1]{Section~\ref{#1}}
\MFUaddmap{\secref}{\Secref}
\makefirstuc{\secref{sec:sentencecase} example} /
\MFUsentencecase{\secref{sec:sentencecase} example}
\end{resultbox}

Argument expansion: \gls{MFUsentencecase} expands its argument
and then skips exclusions whereas \gls{makefirstuc} parses its
argument without expansion and then passes the relevant content to
\gls{glsmakefirstuc}. Note that different results will occur with
the \opt{expanded} and \opt{unexpanded} package options.
For example:
\begin{codebox}
\cmd{usepackage}[\opt{expanded}]\marg{mfirstuc}
\cmd{newcommand}\marg{\cmd{testa}}\marg{sample}
\cmd{newcommand}\marg{\cmd{testb}}\marg{\cmd{testa}\cmd{ }test}
\cbeg{document}
\gls{makefirstuc}\marg{\cmd{testb}} / \gls{xmakefirstuc}\marg{\cmd{testb}} /
\gls{emakefirstuc}\marg{\cmd{testb}} / \gls{MFUsentencecase}\marg{\cmd{testb}}
\cend{document}
\end{codebox}
\begin{resultbox}
\newcommand{\testa}{sample}%
\newcommand{\testb}{\testa\ test}%
\renewcommand*{\glsmakefirstuc}[1]{\MFUsentencecase{#1}}%
\makefirstuc{\testb} / \xmakefirstuc{\testb} /
\emakefirstuc{\testb} / \MFUsentencecase{\testb}
\end{resultbox}
With the default \opt{unexpanded} option the result is:
\begin{resultbox}
\newcommand{\testa}{sample}
\newcommand{\testb}{\testa\ test}
\makefirstuc{\testb} / \xmakefirstuc{\testb} /
\emakefirstuc{\testb} / \MFUsentencecase{\testb}
\end{resultbox}
Note that this is different from the result in earlier versions of
\sty{mfirstuc}.
\begin{codebox}
\cmd{usepackage}\marg{mfirstuc}[=v2.07]
\cmd{newcommand}\marg{\cmd{testa}}\marg{sample}
\cmd{newcommand}\marg{\cmd{testb}}\marg{\cmd{testa}\cmd{ }test}
\cbeg{document}
\gls{makefirstuc}\marg{\cmd{testb}} / \gls{xmakefirstuc}\marg{\cmd{testb}} /
\gls{emakefirstuc}\marg{\cmd{testb}}
\cend{document}
\end{codebox}
This produces:
\begin{resultbox}
SAMPLE TEST / SAMPLE test / Sample test
\end{resultbox}
If this old result is required, either use rollback or try
the \opt{grabfirst} option.

Argument expansion with \idxpl{mapping} (and the default
\opt{unexpanded} option):
\begin{codebox}
\cmd{newrobustcmd}\marg{\cmd{secref}}[1]\marg{section\glstildechar\cmd{ref}\marg{\#1}}
\cmd{newrobustcmd}\marg{\cmd{Secref}}[1]\marg{Section\glstildechar\cmd{ref}\marg{\#1}}
\gls{MFUaddmap}\marg{\cmd{secref}}\marg{\cmd{Secref}}
\cmd{newcommand}\marg{\cmd{testa}}\marg{\cmd{secref}\marg{sec:sentencecase}}
\cmd{newcommand}\marg{\cmd{testb}}\marg{\cmd{testa}\cmd{ }example}
\gls{makefirstuc}\marg{\cmd{testb}} / \gls{xmakefirstuc}\marg{\cmd{testb}} /
\gls{emakefirstuc}\marg{\cmd{testb}} / \gls{MFUsentencecase}\marg{\cmd{testb}}
\end{codebox}
\begin{resultbox}
\newrobustcmd{\secref}[1]{section~\ref{#1}}
\newrobustcmd{\Secref}[1]{Section~\ref{#1}}
\MFUaddmap{\secref}{\Secref}
\newcommand{\testa}{\secref{sec:sentencecase}}
\newcommand{\testb}{\testa\ example}
\makefirstuc{\testb} / \xmakefirstuc{\testb} /
\emakefirstuc{\testb} / \MFUsentencecase{\testb}
\end{resultbox}

\section{Sentence Case Commands}
\label{sec:sentencecasecmds}

\cmddef{MFUsentencecase}
This simply uses \gls{texttitlecasefirst:n}, which is provided by
the \LaTeX3 kernel. Note that this fully expands the argument.
If you use this command, ensure that your \idxpl{semanticcommand} are
robust. For example:
\begin{codebox}
\cmd{newrobustcmd}\marg{\cmd{alert}}[1]\marg{\cmd{textcolor}\marg{red}\marg{\cmd{textbf}\marg{\#1}}}
\gls{MFUsentencecase}\marg{\cmd{alert}\marg{sample} text}
\end{codebox}
\begin{resultbox}
\newrobustcmd{\alert}[1]{\textcolor{red}{\textbf{#1}}}
\MFUsentencecase{\alert{sample} text}
\end{resultbox}
Note that the following will fail:
\begin{badcodebox}
\cmd{newcommand}\marg{\cmd{alert}}[1]\marg{\cmd{textcolor}\marg{red}\marg{\cmd{textbf}\marg{\#1}}}
\gls{MFUsentencecase}\marg{\cmd{alert}\marg{sample} text}
\end{badcodebox}
This is because the expansion that's performed before the case-change will result in:
\begin{badcodebox}
\cmd{textcolor}\marg{Red}\marg{\cmd{textbf}\marg{sample}} text
\end{badcodebox}
This triggers an error since \code{Red} isn't a recognised colour
name.

\cmddef{makefirstuc}
This is the original command provided by \sty+{mfirstuc}, which was
written to assist sentence-casing in the \sty{glossaries} package
and had to take markup into account. It parses its argument to try
to determine which part needs the case-change. The actual
case-change is performed by \gls{glsmakefirstuc}.

As from v2.08, the definition of \gls{makefirstuc} has been updated to use \LaTeX3
code, but the argument is still parsed, which allows for non-robust 
\idxpl{semanticcommand}, and now also takes \idxpl{blocker} and \idxpl{mapping} into
account. For example:
\begin{codebox}
\cmd{newcommand}\marg{\cmd{alert}}[1]\marg{\cmd{textcolor}\marg{red}\marg{\cmd{textbf}\marg{\#1}}}
\gls{makefirstuc}\marg{\cmd{alert}\marg{sample} text}
\end{codebox}
\begin{resultbox}
\newcommand{\alert}[1]{\textcolor{red}{\textbf{#1}}}
\makefirstuc{\alert{sample} text}
\end{resultbox}

The rules used when parsing \code{\gls{makefirstuc}\margm{text}} are as follows:
\begin{enumerate}
\item if \meta{text} is empty do nothing;

\item if \meta{text} consists of a single item or starts
with a group do \code{\gls{glsmakefirstuc}\margm{text}};

\item if \meta{text} starts with a command \meta{cs}:

  \begin{enumerate}
  \item if \meta{cs} is \gls{protect}, skip it and continue to 
  the next step where the command \meta{cs} under inspection 
  is now the one that follows \gls{protect}:

  \item if \meta{cs} has been identified as a \idx{blocker}, just do
  \meta{text} (that is, no case-change is applied);

  \item if \meta{cs} isn't followed by a group then do
  \code{\gls{glsmakefirstuc}\margm{text}};

  \item otherwise assume the format is \code{\meta{cs}\margm{arg}\meta{following}}
  (where \meta{following} may be empty) and then:

    \begin{enumerate}
    \item if \meta{cs} has been \idxc{mapping}{mapped} to
    \meta{Cs} then do \code{\meta{Cs}\margm{arg}\meta{following}};

    \item if \meta{cs} has been identified as an \idx{exclusion}, 
    do \code{\meta{cs}\margm{arg}\gls{makefirstuc}\margm{following}};

    \item otherwise do \code{\meta{cs}\marg{\gls{makefirstuc}\margm{arg}}\meta{following}}.
    \end{enumerate}

  \end{enumerate}

\item otherwise do \code{\gls{glsmakefirstuc}\margm{text}}.
\end{enumerate}

Note that the above algorithm uses recursion. The termination points
are: don't implement a change, replace a command with another
command, or apply the case-change via \gls{glsmakefirstuc}.

For convenience, the following commands are also provided:
\cmddef{xmakefirstuc}
This is simply a shortcut for:
\begin{compactcodebox}
\cmd{expandafter}\gls{makefirstuc}\cmd{expandafter}\margm{text}
\end{compactcodebox}
This ensures the first token in \meta{text} is expanded before being
passed to \gls{makefirstuc}.

\cmddef{emakefirstuc}
This fully expands its argument before passing it to
\gls{makefirstuc}. For example:
\begin{codebox}
\cmd{newcommand}\marg{\cmd{test}}[1]\marg{sample \#1}
\cmd{newcommand}\marg{\cmd{tmp}}\marg{\cmd{test}\marg{text}}
\gls{makefirstuc}\marg{\cmd{tmp}} /
\gls{xmakefirstuc}\marg{\cmd{tmp}} /
\gls{emakefirstuc}\marg{\cmd{tmp}}
\end{codebox}
\begin{resultbox}
\newcommand{\test}[1]{sample #1}
\newcommand{\tmp}{\test{text}}
\makefirstuc{\tmp} /
\xmakefirstuc{\tmp} /
\emakefirstuc{\tmp}
\end{resultbox}
If you don't have any mappings or blockers set up, it's simpler to
use \gls{MFUsentencecase} instead of \gls{emakefirstuc}.

\begin{important}
With \gls{emakefirstuc}, mappings and blockers will only be
detected if they are robust or protected, otherwise they will expand too soon to
be detected.
\end{important}

\cmddef{glsmakefirstuc}
This command is used by \gls{makefirstuc} to perform the
case-change. The \qt{gls} prefix is for historical reasons as the original code
was part of the \sty{glossaries} package. With the default
\opt{unexpanded} option, this command is defined as:
\begin{compactcodebox}
\gls{MFUsentencecase}\marg{\gls+{unexpanded}\margm{text}}
\end{compactcodebox}
The use of \gls{unexpanded} inhibits the expansion of \meta{text}
that would otherwise occur. This allows \gls{makefirstuc} to
maintain as much backward-compatibility with version 2.07 as
possible. This is particularly important when using the
\sty{glossaries} package with a style that automatically converts
the description to \idx{sentence-case}, as there may well be
documents with complex descriptions that contain fragile commands.

The \opt{expanded} package option will redefine \gls{glsmakefirstuc}
to use \gls{MFUsentencecase} without \gls{unexpanded}. The
\opt{grabfirst} package option will redefine \gls{glsmakefirstuc}
to use \gls{mfugrabfirstuc} to emulates the behaviour of
\gls{glsmakefirstuc} in v2.07 and below without using rollback.

\cmddef{mfugrabfirstuc}
This robust command is provided to emulate v2.07 and its use is discouraged.
Note that you may still have different results compared to v2.07, so
you may need to use rollback instead. (Note that the \opt{grabfirst} option
additionally redefines \gls{mfirstucMakeUppercase} to
\gls{MakeUppercase}, which you will also need.)

This applies \gls{mfirstucMakeUppercase} to the first token in \meta{text}
and leaves the remainder unchanged. This won't work if \meta{text}
starts with a \gls{utf8} character unless you use \XeLaTeX\ or
\LuaLaTeX, so avoid using this method where possible. For example:
\begin{codebox}
\cmd{renewcommand}\marg{\gls{mfirstucMakeUppercase}}[1]\marg{\comment{}
  \gls{MakeUppercase}\marg{\#1}\comment{}
}
\gls{mfugrabfirstuc}\marg{sample}
\end{codebox}
This is equivalent to:
\begin{codebox}
\gls{mfirstucMakeUppercase}\marg{s}ample
\end{codebox}
Whereas
\begin{unicodebox}
\cmd{renewcommand}\marg{\gls{mfirstucMakeUppercase}}[1]\marg{\comment{}
  \gls{MakeUppercase}\marg{\#1}\comment{}
}
\gls{mfugrabfirstuc}\marg{\'elite}
\end{unicodebox}
only works with \XeLaTeX\ or \LuaLaTeX.

\begin{warning}
As with earlier implementations of \gls{makefirstuc} that 
tried to only apply the case-change to the first token, 
this won't produce the desired result if the argument starts with a
punctuation character.
\end{warning}

For example:
\begin{codebox}
\gls{mfugrabfirstuc}\marg{`sample'}
\end{codebox}
This is equivalent to:
\begin{compactcodebox}
\gls{mfirstucMakeUppercase}\marg{`}sample'
\end{compactcodebox}
so no case-change is applied.

\section{Exclusions}
\label{sec:exclusions}

\begin{information}
Exclusions will apply to all \LaTeX3 case-changing commands, so will
also affect \gls{mfirstucMakeUppercase}, but this is generally
desirable.
\end{information}

\cmddef{MFUexcl}
Identifies the text-block command \code{\meta{cs}\margm{arg}} as
an \idx{exclusion}. That is, one that should have its argument
excluded from a case-change.

Internally, \gls{MFUexcl} adds \meta{cs} to \LaTeX3's exclusion list
\gls{ltextcaseexcludeargtl}, which means that \gls{MFUsentencecase}
will skip the command and its argument and apply the case-change to
the following content. Some common commands (\gls{begin} \gls{cite}
\gls{end} \gls{label} and \gls{ref}) are automatically added by the
\LaTeX3 kernel.
The exclusions are also recognised by \gls{makefirstuc} when it
parses its argument.

\begin{information}
The command \gls{NoCaseChange} is automatically treated as an
exclusion by the \LaTeX3 case-changing commands with recent \LaTeX\
kernels. You may want to add it as a blocker for \gls{makefirstuc}
and keep \gls{MFUskippunc} for exclusions.

Note that \gls{ensuremath} is added as an exclusion by \sty{mfirstuc} otherwise
\gls{makefirstuc} will pass its argument to \gls{MFUsentencecase},
which will cause a problem.
\end{information}

Another way of identifying content that should be excluded with
\gls{makefirstuc} is to encapsulate it with:
\cmddef{MFUskippunc}
This is a robust command that simply does its argument and is
automatically added to the exclusion list. This may be used for
cases where the excluded command isn't a simple text-block command
that only has one mandatory argument or where leading punctuation is
followed by a \idx{blocker} or \idx{mapping}.

The command name stems from earlier versions where leading
\idx{punctuation} needed to be skipped. This is no longer necessary,
but the command remains as a general purpose robust exclusion command.

For example, \gls{glsadd} (provided by \sty{glossaries}) should have
its argument skipped, since its argument is a label, so the
following will ensure that \code{\gls{glsadd}\margm{label}} will be
skipped, and the case-change will be applied to the following text
for both \gls{MFUsentencecase} and \gls{makefirstuc}.
\begin{codebox}
\gls{MFUexcl}\marg{\gls{glsadd}}
\gls{makefirstuc}\marg{\gls{glsadd}\marg{ex}some text}
\gls{MFUsentencecase}\marg{\gls{glsadd}\marg{ex}some text}
\end{codebox}
This will be equivalent to:
\begin{compactcodebox}
\gls{glsadd}\marg{ex}Some text
\end{compactcodebox}
However, \gls{glsadd} can take an optional argument which, if
present, will cause a problem. For example:
\begin{badcodebox}
\gls{MFUexcl}\marg{\gls{glsadd}}
\gls{makefirstuc}\marg{\gls{glsadd}\oarg{counter=section}\marg{ex}some text}
\gls{MFUsentencecase}\marg{\gls{glsadd}\oarg{counter=section}\marg{ex}some text}
\end{badcodebox}
Both commands will cause the following error:
\begin{transcript}
! Package glossaries Error: Glossary entry `\nlctopensqbracket' has not been defined.
\end{transcript}
This is because the open square bracket is assumed to be the
argument of \gls{glsadd}, so this effectively becomes:
\begin{compactcodebox}
\gls{glsadd}\marg{\nlctopensqbracket}Counter=section\nlctclosesqbracket exsome text
\gls{glsadd}\marg{\nlctopensqbracket}Counter=section\nlctclosesqbracket exsome text
\end{compactcodebox}
which means that now \code{\nlctopensqbracket} is considered the label and everything
that follows is just text.

For this situation to work, you need to encapsulate the problematic
content with an exclusion command, such as \gls{NoCaseChange} or \gls{MFUskippunc}:
\begin{codebox}
\gls{makefirstuc}\marg{\gls{MFUskippunc}\marg{\gls{glsadd}\oarg{counter=section}\marg{ex}}some text}
\end{codebox}
This will also work with \gls{MFUsentencecase} because
\sty{mfirstuc} automatically adds \gls{MFUskippunc} to the exclusion
list.

\begin{information}
As from \sty{glossaries} v4.50, \gls{glsadd} is automatically added
as an exclusion, but be aware of the problem with using the optional
argument, as described above.
\end{information}

\Idx{punctuation} characters are skipped by \gls{MFUsentencecase}.
For example:
\begin{coderesult}
\gls{MFUsentencecase}\marg{`word'}
\tcblower
\MFUsentencecase{`word'}
\end{coderesult}
However, leading \idx{punctuation} will result in \gls{makefirstuc}
passing its entire argument to \gls{MFUsentencecase} (since the
argument doesn't start with \code{\meta{cs}\margm{arg}}), which
means that \gls{makefirstuc} won't detect any \idx{blocker} or
\idx{mapping}.

For example:
\begin{codebox}
\gls{MFUblocker}\marg{\gls+{nameref}}
\cmd{newcommand}*\marg{\cmd{qt}}[1]\marg{``\#1''}
\gls{makefirstuc}\marg{``\gls{nameref}\marg{sec:sentencecase} section''} /
\gls{makefirstuc}\marg{\gls{MFUskippunc}\marg{``}\gls{nameref}\marg{sec:sentencecase} section''} /
\gls{makefirstuc}\marg{\cmd{qt}\marg{\gls{nameref}\marg{sec:sentencecase} section}}
\end{codebox}
\begin{resultbox}
\MFUblocker{\nameref}
\makefirstuc{``\nameref{sec:sentencecase} section''} /
\makefirstuc{\MFUskippunc{``}\nameref{sec:sentencecase} section''} /
\makefirstuc{\qt{\nameref{sec:sentencecase} section}}
\end{resultbox}
If you are using a package such as \sty{csquotes}, bear in mind that
if the command is followed by an asterisk (a \qt{starred command})
or an optional argument then it won't fit the expected
\code{\meta{cs}\margm{arg}} format and unexpected results will occur.

\section{Blockers}
\label{sec:blockers}

A \idx{blocker} is a command that prevents any case-change if it occurs at
the start of \gls{makefirstuc} or after the argument of an
\idx{exclusion}. Blockers are not supported by
\gls{MFUsentencecase} but are instead treated as exclusions. 

\cmddef{MFUblocker}
Identifies \meta{cs} as a \idx{blocker}. Since \idxpl{blocker}
aren't supported by \gls{MFUsentencecase}, this automatically
implements \code{\gls{MFUexcl}\margm{cs}} to protect its argument
from \gls{MFUsentencecase}, but it won't prevent subsequent content
from being changed.

For example:
\begin{codebox}
\gls{MFUblocker}\marg{\gls+{nameref}}
\gls{makefirstuc}\marg{\gls{nameref}\marg{sec:sentencecase} section} 
\end{codebox}
\begin{resultbox}
\MFUblocker{\nameref}
\makefirstuc{\nameref{sec:sentencecase} section}
\end{resultbox}

In the following, the \idx{blocker} isn't detected by
\gls{makefirstuc} because the content doesn't start with 
\code{\meta{cs}\margm{arg}} or
\code{\cmd{protect}\meta{cs}\margm{arg}}. This means that the entire
content is passed to \gls{MFUsentencecase} which treats
\gls{nameref} as an \idx{exclusion}:
\begin{codebox}
\gls{MFUblocker}\marg{\gls{nameref}}
\gls{makefirstuc}\marg{\cmd{relax}\gls{nameref}\marg{sec:sentencecase} section} 
\end{codebox}
\begin{resultbox}
\MFUblocker{\nameref}
\makefirstuc{\relax\nameref{sec:sentencecase} section}
\end{resultbox}

\begin{important}
If a \idxc{blocker}{blocking command} is inside the definition of
another command, it won't be visible to \gls{makefirstuc} unless
the other command is expanded before applying \gls{makefirstuc}.
For example, by using \gls{xmakefirstuc} or \gls{emakefirstuc}.
If it doesn't get expanded until after it has been passed to
\gls{MFUsentencecase}, then it will be treated as an \idx{exclusion}
instead.
\end{important}

Recent \LaTeX\ kernels provide \gls{NoCaseChange} and automatically
add it as an \idx{exclusion}. You may want to add it as a
\idx{blocker} for \gls{makefirstuc}. For example:
\begin{codebox}
\gls{makefirstuc}\marg{\gls{ensuremath}\marg{\cmd{alpha}}-particle} /
\gls{makefirstuc}\marg{\idx{dollar}\cmd{alpha}\idx{dollar}-particle} /
\gls{MFUsentencecase}\marg{\gls{ensuremath}\marg{\cmd{alpha}}-particle} /
\gls{MFUsentencecase}\marg{\idx{dollar}\cmd{alpha}\idx{dollar}-particle}
\codepar
\gls{MFUblocker}\marg{\gls{NoCaseChange}}\comment{}
\gls{makefirstuc}\marg{\gls{ensuremath}\marg{\cmd{alpha}}-particle} /
\gls{makefirstuc}\marg{\gls{NoCaseChange}\marg{\idx{dollar}\cmd{alpha}\idx{dollar}}-particle} /
\gls{MFUsentencecase}\marg{\gls{ensuremath}\marg{\cmd{alpha}}-particle} /
\gls{MFUsentencecase}\marg{\gls{NoCaseChange}\marg{\idx{dollar}\cmd{alpha}\idx{dollar}}-particle}
\end{codebox}
Note that \sty{mfirstuc} adds \gls{ensuremath} as an exclusion so
\gls{makefirstuc} will skip it. Whereas the example above that
starts with \idx{dollar} will have the entire argument passed to
\gls{MFUsentencecase}, which skips the maths content. 
In the first paragraph, \gls{NoCaseChange} is only an
\idx{exclusion}, but in the second paragraph it's also a
\idx{blocker}.
\begin{resultbox}
Exclusion:
\makefirstuc{\ensuremath{\alpha}-particle} /
\makefirstuc{$\alpha$-particle} /
\MFUsentencecase{\ensuremath{\alpha}-particle} /
\MFUsentencecase{$\alpha$-particle}

Blocker:
\MFUblocker{\NoCaseChange}%
\makefirstuc{\ensuremath{\alpha}-particle} /
\makefirstuc{\NoCaseChange{$\alpha$}-particle} /
\MFUsentencecase{\ensuremath{\alpha}-particle} /
\MFUsentencecase{\NoCaseChange{$\alpha$}-particle}
\end{resultbox}

\section{Mappings}
\label{sec:mappings}

A \idx{mapping} indicates that one command should be substituted for
another, instead of applying a case-change. The assumption is that
the substituted command should perform the case-change instead.
\Idxpl{mapping} are not supported by \gls{MFUsentencecase} 
but are instead treated as exclusions.

\cmddef{MFUaddmap}
Identifies a mapping which indicates that \gls{makefirstuc} should
replace \meta{cs1} with \meta{cs2} and not apply a case-change.
This automatically implements:
\begin{compactcodebox}
\gls{MFUexcl}\margm{cs1}\gls{MFUblocker}\margm{cs2}
\end{compactcodebox}
This means that \meta{cs2} is identified as a \idx{blocker} (since
it's assumed to already be a \idx{sentence-case} command) and
\meta{cs1} is identified as an \idx{exclusion} to protect its
argument from \gls{MFUsentencecase}, which doesn't support
\idxpl{mapping}.

\begin{information}
If either \meta{cs1} or \meta{cs2} is empty, no mapping is established, but an
\idx{exclusion} or \idx{blocker} will be set for the non-empty argument.
\end{information}

For example (with \sty{glossaries}):
\begin{codebox}
\gls{MFUaddmap}\marg{\gls+{gls}}\marg{\gls+{Gls}}
\gls{makefirstuc}\marg{\gls{gls}\marg{ex} some text}
\end{codebox}
This will be converted to:
\begin{compactcodebox}
\gls{Gls}\marg{ex} some text
\end{compactcodebox}
Note that this and similar \idxpl{mapping} are automatically added
in \sty{glossaries} v4.50+ and \sty{glossaries-extra} v1.49+.

\begin{important}
If a \idxc{mapping}{mapped command} is inside the definition of
another command, it won't be visible to \gls{makefirstuc} unless
the other command is expanded before applying \gls{makefirstuc}.
For example, by using \gls{xmakefirstuc} or \gls{emakefirstuc}.
If it doesn't get expanded until after it has been passed to
\gls{MFUsentencecase}, then it will be treated as an \idx{exclusion}
instead.
\end{important}

\section{Package Options}
\label{sec:pkgoptions}

\optiondef{expanded}
Redefines \gls{glsmakefirstuc} to simply use \gls{MFUsentencecase}.

\optiondef{unexpanded}
Redefines \gls{glsmakefirstuc} to use \gls{MFUsentencecase}
without expanding its argument.

\optiondef{grabfirst}
Redefines \gls{glsmakefirstuc} to use \gls{mfugrabfirstuc} and also
redefines \gls{mfirstucMakeUppercase} to use \gls{MakeUppercase}.

This option is best avoided and is only provided to emulate the v2.07
behaviour of \gls{glsmakefirstuc}. However, you may still have
different results compared to v2.07, so you may need to use rollback
instead.

\chapter{Title-Case}
\label{sec:capitalisewords}

The \idx{title-case} commands are designed to convert the first letter of each
word in a phrase to uppercase. These commands are robust.
\cmddef{capitalisewords}
This command applies a \idx{sentence-case} command to each word in \meta{text}
where the space character is used as the word separator. Note that
it has to be an ordinary space character, not another form of space,
such as \idx{nbsp} or \gls{space}. Note that no expansion is performed
on \meta{text}.
For example:
\begin{coderesult}
\gls{capitalisewords}\marg{a sample phrase}
\tcblower
\capitalisewords{a sample phrase}
\end{coderesult}
See \sectionref{sec:nocap} for excluding words (such as \qt{of})
from the case-changing.

\begin{information}
This isn't the same as the \LaTeX3 command \gls{texttitlecase:n},
which converts the first letter to \idx{uppercase} and all other
letters to \idx{lowercase}.
\end{information}

For convenience, there are shortcut commands if expansion is
required before parsing the argument:
\cmddef{xcapitalisewords}
This is a shortcut for:
\begin{compactcodebox}
\cmd{expandafter}\gls{capitalisewords}\cmd{expandafter}\margm{text}
\end{compactcodebox}
\cmddef{ecapitalisewords}
This fully expands \meta{text} before passing it to
\gls{capitalisewords}.

The parser used by \gls{capitalisewords} first splits up the text on
each space character. Each of these space-separated words may
actually be a compound, so further parsing is performed on each
\qt{word}. The divisions within the compound word should be marked
up with:
\cmddef{MFUwordbreak}
For example:
\begin{coderesult}
\gls{capitalisewords}\marg{a 
big\gls{MFUwordbreak}\marg{/}small idea}
\tcblower
\capitalisewords{a big\MFUwordbreak{/}small idea}
\end{coderesult}
Each sub-word within the compound word is encapsulated with:
\cmddef{MFUcapword}
Since it's inconvenient to have to markup every hyphen,
\gls{MFUcapword} can be enabled to check for hyphens.
 
\cmddef{ifMFUhyphen}
This conditional determines whether or not \gls{MFUcapword} should
consider a hyphen a word break. If this conditional is true, then
\gls{MFUcapword} will encapsulate its argument with:
\cmddef{MFUhyphencapword}
This will parse \meta{text} for hyphen characters and apply the case
change to each hyphen-separated word.  Otherwise \gls{MFUcapword}
will treat its argument as a single word.

The conditional can be set to true with:
\cmddef{MFUhyphentrue}
and switched back off with:
\cmddef{MFUhyphenfalse}

For example:
\begin{codebox}
\gls{capitalisewords}\marg{server-side includes} /
\gls{MFUhyphentrue}
\gls{capitalisewords}\marg{server-side includes}
\end{codebox}
\begin{resultbox}
\capitalisewords{server-side includes} /
\MFUhyphentrue
\capitalisewords{server-side includes}
\end{resultbox}

The actual case-change of each word is performed with:
\cmddef{MFUcapwordfirstuc}
This defaults to \code{\gls{makefirstuc}\margm{word}} but may be
redefined to use \gls{MFUsentencecase}, if preferred.

\begin{important}
Hyphens and \gls{MFUwordbreak} must be visible to the parser that
searches for word breaks. This means they won't be detected if they
are within a group or in the definition of a command.
\end{important}

Formatting for the entire phrase must go outside
\gls{capitalisewords} (unlike \gls{makefirstuc}).
For example:
\begin{codebox}
\gls{capitalisewords}\marg{\cmd{emph}\marg{a sample phrase}} /
\cmd{emph}\marg{\gls{capitalisewords}\marg{a sample phrase}}
\end{codebox}
\begin{resultbox}
\capitalisewords{\emph{a sample phrase}} /
\emph{\capitalisewords{a sample phrase}}
\end{resultbox}

If your phrase is likely to contain formatting commands, you can instead use:
\cmddef{capitalisefmtwords}
where \meta{text} may be just words (as with \gls{capitalisewords}):
\begin{compactcodebox}
\gls{capitalisefmtwords}\margm{words}
\end{compactcodebox}
or may be entirely enclosed in a formatting command in the form:
\begin{compactcodebox}
\gls{capitalisefmtwords}\marg{\meta{cs}\margm{words}}
\end{compactcodebox}
or contain formatted sub-phrases:
\begin{compactcodebox}
\gls{capitalisefmtwords}\marg{\meta{words} \meta{cs}\margm{sub-phrase} \meta{words}}
\end{compactcodebox}
The starred form only permits a text-block command at the
start of the phrase. See \sectionref{sec:titlecaseexamples} for
examples.

\begin{warning}
Avoid declarations, such as \cmd{bfseries} or \cmd{em}.
\end{warning}

If expansion is required, you can use:
\cmddef{xcapitalisefmtwords}
which is a shortcut for:
\begin{compactcodebox}
\cmd{expandafter}\gls{capitalisefmtwords}\cmd{expandafter}\margm{text}
\end{compactcodebox}
(The star modifier will be applied with 
\code{\gls{xcapitalisefmtwords}*} in an appropriate manner.)

\cmddef{ecapitalisefmtwords}
This will fully expand its argument before passing it to
\gls{capitalisefmtwords}. Again, the star modifier may be used.

\begin{important}
The unstarred \gls{capitalisefmtwords} is only designed for phrases that contain
text-block commands with a single
argument, which should be a word or sub-phrase. Anything
more complicated is likely to break. Instead, use the
starred form or \gls{capitalisewords}.
\end{important}

\section{Excluding Words From Case-Changing}
\label{sec:nocap}

\glsadd{exclusion-word}Some words typically shouldn't have their case changed unless they
occur at the start. These words can be identified with:
\cmddef{MFUnocap}
This only has a local effect. The global version is:
\cmddef{gMFUnocap}
The list of words that shouldn't be capitalised can be cleared
using:
\cmddef{MFUclear}


For example:
\begin{codebox}
\gls{capitalisewords}\marg{the wind in the willows}
\codepar
\gls{MFUnocap}\marg{in}\comment{}
\gls{MFUnocap}\marg{the}\comment{}
\codepar
\gls{capitalisewords}\marg{the wind in the willows}
\end{codebox}
\begin{resultbox}
\capitalisewords{the wind in the willows}

\MFUnocap{in}%
\MFUnocap{the}%

\capitalisewords{the wind in the willows}
\end{resultbox}

Since the case-change is ultimately performed by \gls{makefirstuc},
you can also use an \idx{exclusion} to prevent an individual word
from being changed. For example:
\begin{codebox}
\cmd{newcommand}\marg{\cmd{NoChange}}[1]\marg{\#1}
\gls{MFUexcl}\marg{\cmd{NoChange}}
\gls{MFUclear}
\gls{capitalisewords}\marg{the \cmd{NoChange}\marg{wind} in the willows}
\end{codebox}
\begin{resultbox}
\providecommand{\NoChange}[1]{#1}
\MFUexcl{\NoChange}
\MFUclear
\capitalisewords{the \NoChange{wind} in the willows}
\end{resultbox}
This can also work if you redefine \gls{MFUcapwordfirstuc} to use
\gls{MFUsentencecase} provided the exclusion command doesn't expand
(so \cmd{NoChange} would need to be protected or made robust in the above
example). 

\begin{important}
Exceptions only apply to (non-leading) whole words or words separated with
\gls{MFUwordbreak} but not to parts of a hyphenated
word that are split by \gls{MFUhyphencapword}.
\end{important}

Examples:
\begin{enumerate}
\item
Exceptions aren't applied if \gls{MFUwordbreak} occurs before the
first space.
\begin{codebox}
\gls{MFUnocap}\marg{a}\gls{MFUnocap}\marg{the}\comment{}
\gls{capitalisewords}\marg{a\gls{MFUwordbreak}\marg{/}the something}
\end{codebox}
\begin{resultbox}
\MFUnocap{a}\MFUnocap{the}%
\capitalisewords{a\MFUwordbreak{/}the something}
\end{resultbox}

\item
Exceptions are applied for non-leading words:
\begin{codebox}
\gls{MFUnocap}\marg{and}\gls{MFUnocap}\marg{or}\comment{}
\gls{capitalisewords}\marg{one and\gls{MFUwordbreak}\marg{/}or another}
\end{codebox}
\begin{resultbox}
\MFUnocap{and}\MFUnocap{or}%
\capitalisewords{one and\MFUwordbreak{/}or another}
\end{resultbox}

\item
Exceptions aren't applied for hyphenated parts:
\begin{codebox}
\gls{MFUhyphentrue}
\gls{MFUnocap}\marg{and}\gls{MFUnocap}\marg{or}\comment{}
\gls{capitalisewords}\marg{one and-or another}
\end{codebox}
\begin{resultbox}
\MFUhyphentrue
\MFUnocap{and}\MFUnocap{or}%
\capitalisewords{one and-or another}
\end{resultbox}
\end{enumerate}

\pkgdef{mfirstuc-english}
The supplementary package \sty{mfirstuc-english} loads \sty{mfirstuc} and uses
\gls{MFUnocap} to add common English articles and conjunctions, such
as \qt{a}, \qt{an}, \qt{and}, \qt{but}. You may want to add other
words to this list, such as prepositions but, as there's some
dispute over whether prepositions should be capitalised, I~don't
intend to add them to this package. Note that you need to explicitly
load \sty{mfirstuc-english} if you require it. There's no automatic
language detection performed by \sty{mfirstuc}.

If you want to write a similar package for another language, all you
need to do is create a file with the extension \filefmt{.sty}
that starts with:
\begin{compactcodebox}
\cmd{NeedsTeXFormat}\marg{LaTeX2e}
\end{compactcodebox}
The next line should identify the package. For example, if you have
called the file \filefmt{mfirstuc-french.sty} then you need:
\begin{compactcodebox}
\cmd{ProvidesPackage}\marg{mfirstuc-french}
\end{compactcodebox}
It's a good idea to also add a version in the final optional
argument, for example:
\begin{compactcodebox}
\cmd{ProvidesPackage}\marg{mfirstuc-french}[2014/07/30 v1.0]
\end{compactcodebox}
Next load \sty{mfirstuc}:
\begin{compactcodebox}
\cmd{RequirePackage}\marg{mfirstuc}
\end{compactcodebox}
Now add all your \gls{MFUnocap} commands. For example:
\begin{compactcodebox}
\gls{MFUnocap}\marg{de}
\end{compactcodebox}
At the end of the file add:
\begin{compactcodebox}
\cmd{endinput}
\end{compactcodebox}

Put the file somewhere on \TeX's path, and now you can use this
package in your document. You might also consider
\href{http://ctan.org/upload}{uploading it to CTAN} in case
other users find it useful.


\section{PDF Bookmarks}
\label{sec:pdfbookmarks}

If you are using \sty{hyperref} and want to use
\gls{capitalisewords} or \gls{capitalisefmtwords} (or the expanded
variants) in a section heading, the PDF bookmarks won't be able to
use the command as it's not expandable, so you will get a warning
that looks like:
\begin{transcript}
Package hyperref Warning: Token not allowed in a PDF string 
(PDFDocEncoding):
(hyperref)                removing `\gls{capitalisewords}'
\end{transcript}

If you want to provide an alternative for the PDF bookmark, you can
use \sty{hyperref}'s \gls{texorpdfstring} command. For example:
\begin{codebox}
\cmd{chapter}\marg{\gls{texorpdfstring}
  \marg{\gls{capitalisewords}\marg{a book of rhyme}}\comment{ TeX}
  \marg{A Book of Rhyme}\comment{ PDF}
}
\end{codebox}
Alternatively, you can use \sty{hyperref}'s mechanism for
disabling commands within the bookmarks. For example:
\begin{codebox*}
\gls{pdfstringdefDisableCommands}\marg{\comment{}
 \cmd{let}\gls{capitalisewords}\cmd{@firstofone}
}
\end{codebox*}
The same applies to \gls{makefirstuc}. You can, however, use
the expandable \gls{MFUsentencecase}. So you may prefer:
\begin{codebox*}
\gls{pdfstringdefDisableCommands}\marg{\comment{}
 \cmd{let}\gls{capitalisewords}\cmd{MFUsentencecase}
 \cmd{let}\gls{makefirstuc}\cmd{MFUsentencecase}
}
\end{codebox*}

See the \sty{hyperref} manual for further details.

\section{Examples}
\label{sec:titlecaseexamples}

\begin{enumerate}
\item Text only:
\begin{coderesult}
\gls{capitalisewords}\marg{a little book of rhyme}
\tcblower
\capitalisewords{a little book of rhyme}
\end{coderesult}

\item Excluding words (see \sectionref{sec:nocap}):
\begin{coderesult}
\gls{MFUnocap}\marg{of}
\gls{capitalisewords}\marg{a little book of rhyme}
\tcblower
\MFUnocap{of}
\capitalisewords{a little book of rhyme}
\end{coderesult}

\item \gls{space} isn't recognised as a word boundary:
\begin{codebox}
\gls{capitalisewords}\marg{a book of rhyme.}
\codepar
\gls{capitalisewords}\marg{a book\gls{space} of rhyme.}
\end{codebox}
\begin{resultbox}
\capitalisewords{a book of rhyme.}

\capitalisewords{a book\space of rhyme.}
\end{resultbox}

\item Phrase entirely enclosed in a formatting command:
\begin{codebox}
\gls{capitalisefmtwords}\marg{\cmd{emph}\marg{a small book of rhyme}}
\end{codebox}
\begin{resultbox}
\capitalisefmtwords{\emph{a small book of rhyme}}
\end{resultbox}

\item Sub-phrase enclosed in a formatting command:
\begin{codebox}
\gls{capitalisefmtwords}\marg{a \cmd{emph}\marg{small book} of rhyme}
\end{codebox}
\begin{resultbox}
\capitalisefmtwords{a \emph{small book} of rhyme}
\end{resultbox}

\item Nested text-block commands:
\begin{codebox}
\gls{capitalisefmtwords}\marg{\cmd{textbf}\marg{a \cmd{emph}\marg{small book}} of rhyme}
\end{codebox}
\begin{resultbox}
\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme}
\end{resultbox}

\item Formatting and case-change exception (see \sectionref{sec:nocap}):
\begin{codebox}
\gls{MFUnocap}\marg{of}
\gls{capitalisefmtwords}\marg{\cmd{textbf}\marg{a \cmd{emph}\marg{small book}} of rhyme}
\end{codebox}
\begin{resultbox}
\MFUnocap{of}
\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme}
\end{resultbox}

\item Starred form:
\begin{codebox}
\gls{MFUnocap}\marg{of}
\gls{capitalisefmtwords}*\marg{\cmd{emph}\marg{a small book of rhyme}}
\end{codebox}
\begin{resultbox}
\MFUnocap{of}
\capitalisefmtwords*{\emph{a small book of rhyme}}
\end{resultbox}

\item The starred form also works with just text (no text-block
command):
\begin{codebox}
\gls{MFUnocap}\marg{of}
\gls{capitalisefmtwords}*\marg{a small book of rhyme}
\end{codebox}
\begin{resultbox}
\MFUnocap{of}
\capitalisefmtwords*{a small book of rhyme}
\end{resultbox}

\item Expansion:
\begin{codebox}
\cmd{newcommand}\marg{\cmd{abc}}\marg{\cmd{xyz}\gls+{space} four five}
\cmd{newcommand}\marg{\cmd{xyz}}\marg{one two three}
No expansion: \gls{capitalisewords}\marg{\cmd{abc}}.
\codepar
First object one-level expansion: \gls{xcapitalisewords}\marg{\cmd{abc}}.
\codepar
Fully expanded: \gls{ecapitalisewords}\marg{\cmd{abc}}.
\end{codebox}
\begin{resultbox}
\newcommand{\abc}{\xyz\space four five}
\newcommand{\xyz}{one two three}
No expansion: \capitalisewords{\abc}.

First object one-level expansion: \xcapitalisewords{\abc}.

Fully expanded: \ecapitalisewords{\abc}.
\end{resultbox}

Remember that the spaces need to be explicit. In the second case
above, using \gls{xcapitalisewords}, the space before \qt{four} has
been hidden within \gls{space} so it's not recognised as a word
boundary, but in the third case, \gls{space} has been expanded to an
actual space character.


\end{enumerate}

If there is a text-block command within the argument of the
starred form, it's assumed to be at the start of the argument.
Unexpected results can occur if there are other commands.
For example:
\begin{badcodebox}
\gls{MFUnocap}\marg{of}
\gls{capitalisefmtwords}*\marg{\cmd{emph}\marg{a small} book \cmd{textbf}\marg{of rhyme}}
\end{badcodebox}
\begin{resultbox}
\MFUnocap{of}
\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}}
\end{resultbox}
In this case \code{\cmd{textbf}\marg{of rhyme}} is considered a
single word. Similarly if the text-block command occurs
in the middle of the argument:
\begin{badcodebox}
\gls{MFUnocap}\marg{of}
\gls{capitalisefmtwords}*\marg{a \cmd{emph}\marg{very small} book of rhyme}
\end{badcodebox}
\begin{resultbox}
\MFUnocap{of}
\capitalisefmtwords*{a \emph{very small} book of rhyme}
\end{resultbox}
In this case \code{\cmd{emph}\marg{very small}} is considered a
single word.

Grouping causes interference.
As with all the commands described here, avoid declarations.
\begin{badcodebox}
\gls{capitalisefmtwords}\marg{\marg{\cmd{bfseries} a \cmd{emph}\marg{small book}} of rhyme}
\end{badcodebox}

\begin{information}
As a general rule, it's better to define \idxpl{semanticcommand} rather
than directly using font commands and declarations within the
document.
\end{information}

Avoid complicated commands in the unstarred version. For example,
the following breaks:
\begin{badcodebox}
\cmd{newcommand}*\marg{\cmd{swap}}[2]\marg{\marg{\#2}\marg{\#1}}
\gls{capitalisefmtwords}\marg{a \cmd{swap}\marg{bo}\marg{ok} of rhyme}
\end{badcodebox}
However it can work with the starred form and the simpler
\gls{capitalisewords}:
\begin{codebox}
\cmd{newcommand}*\marg{\cmd{swap}}[2]\marg{\marg{\#2}\marg{\#1}}
\gls{capitalisefmtwords}*\marg{a \cmd{swap}\marg{bo}\marg{ok} of rhyme}
\codepar
\gls{capitalisewords}\marg{a \cmd{swap}\marg{bo}\marg{ok} of rhyme}
\end{codebox}
\begin{resultbox}
\newcommand*{\swap}[2]{{#2}{#1}}
\capitalisefmtwords*{a \swap{bo}{ok} of rhyme}

\capitalisewords{a \swap{bo}{ok} of rhyme}
\end{resultbox}
Note that the case change is applied to the first argument.

\chapter{Miscellaneous}
\label{sec:misc}

\section{Saving \Glsfmtplural{exclusion}, \Glsfmtplural{blocker} and 
\Glsfmtplural{mapping} in the \exttext{aux} File}
\label{sec:savetoaux}

If the \idxpl{exclusion}, \idxpl{mapping} and \idxpl{blocker} are
required by some external tool, the information can be saved in the
\ext+{aux} file.

\cmddef{MFUsaveatend}
This saves the information at the end of the document using a delayed
write. This means that it can register all information identified 
throughout the document, but there's a chance the document may end
before the write takes place (for example, if the last page only
contains floats). This command may be counteracted by:
\cmddef{MFUsave}
This saves the information using a protected write at the point
where this command occurs, which may be too soon if additional
\idxpl{exclusion}, \idxpl{mapping} or \idxpl{blocker} are identified
later. This command will counteract any instance of
\gls{MFUsaveatend}, regardless of whether or not \gls{MFUsaveatend}
comes before or after \gls{MFUsave}.

The associated \ext{aux} commands are listed below. In each case, a
definition is provided in the \ext{aux} file that does nothing.
\cmddef{@mfu@excls}
Lists all \idxpl{exclusion}.
For example:
\begin{compactcodebox*}
\gls{@mfu@excls}\marg{\gls{begin} \gls{cite} \gls{end} \gls{label}
\gls{ref} \gls{cite} \gls{NoCaseChange} \gls{ensuremath}
\gls{MFUskippunc} \gls{gls} \gls{glspl}}
\end{compactcodebox*}

\cmddef{@mfu@blockers}
Lists all \idxpl{blocker}.
For example:
\begin{compactcodebox*}
\gls{@mfu@blockers}\marg{\gls{Gls} \gls{Glspl} }
\end{compactcodebox*}

\cmddef{@mfu@mappings}
Lists all \idxpl{mapping} as a \keyval\ list.
For example:
\begin{compactcodebox*}
\gls{@mfu@mappings}\marg{ \marg{\gls{gls} }= \marg{\gls{Gls} }, \marg{\gls{glspl} }= \marg{\gls{Glspl} }}
\end{compactcodebox*}

\section{All-Caps}
\label{sec:allcaps}

\cmddef{mfirstucMakeUppercase}
This command was originally used to perform the actual conversion to
\idx+{uppercase} and was defined to use command \gls{MakeUppercase}.
The \sty{glossaries} package (before v4.50) formerly loaded the
\sty{textcase} package and redefined \gls{mfirstucMakeUppercase} to
use \gls{MakeTextUppercase}, which was better than
\gls{MakeUppercase}.

The \sty{textcase} package has been deprecated as from 2022 and
it now simply sets \gls{MakeTextUppercase} to \gls{MakeUppercase}
because the new kernel now defines \gls{MakeUppercase} to use the
newer \LaTeX3 command \gls{textuppercase:n}. Although that command
is expandable, \gls{MakeUppercase} is robust.

As from v2.08, \sty{mfirstuc} now defines \gls{mfirstucMakeUppercase}
so that it uses \gls{texttitlecasefirst:n} directly, rather than
indirectly through \gls{MakeUppercase}, which means that it's now
expandable. However, \gls{mfirstucMakeUppercase} is no longer used
by \sty{mfirstuc} except in \gls{mfugrabfirstuc}, which is provided
to emulate v2.07. Note that the \opt{grabfirst} option will also
redefine \gls{mfirstucMakeUppercase} to use \gls{MakeUppercase}.

\section{UTF-8}
\label{sec:utf8}

\begin{information}
See \blog{binary-files-text-files-and-file-encodings/}{Binary
Files, Text Files and File Encodings} if you are confused about how
file encodings, such as \gls{utf8}, relate to text files.
\end{information}

This section only applies to rollback or the use of \gls{mfugrabfirstuc}
(implemented via the \opt{grabfirst} option).

Prior to version 2.08, the case-change applied by the
\gls{glsmakefirstuc} command worked by utilizing the fact that, in
most cases, \TeX\ doesn't require a regular argument to be enclosed
in braces if it only consists of a single token. (This is why you
can do, say, \code{\cmd{frac}12} instead of
\code{\cmd{frac}\marg{1}\marg{2}} or \code{x\char`\^2}
instead of \code{x\char`\^\marg{2}}, although this
practice is discouraged by some.)

A~simplistic version of the original \gls{glsmakefirstuc} command is:
\begin{codebox}
\cmd{newcommand}*\marg{\cmd{FirstUC}}[1]\marg{\gls{MakeUppercase} \#1}
\end{codebox}
Here
\begin{codebox}
\cmd{FirstUC}\marg{abc}
\end{codebox}
is equivalent to
\begin{codebox}
\gls{MakeUppercase} abc
\end{codebox}
and since \gls{MakeUppercase} requires an argument, it grabs the
first token (the character \qt{a} in this case) and uses that as the
argument so that the result is \qt{Abc}. This behaviour can be
achieved with \gls{mfugrabfirstuc}.

Unfortunately, this will fail if the content starts with a \gls{utf8}
character and you are using \pdfLaTeX, where each octet of the
\gls{utf8} character is a separate token. This isn't a problem 
with \XeLaTeX\ and \LuaLaTeX\ which both treat the entire multibyte
character as a single token.

\LaTeX3 now provides \gls{texttitlecasefirst:n}
to convert the first character to uppercase, so now the
case-change can be applied with:
\begin{codebox}
\cmd{ExplSyntaxOn}
\gls{texttitlecasefirst:n}\marg{élite}
\cmd{ExplSyntaxOff}
\end{codebox}
This is exactly what \gls{MFUsentencecase} does without the need to
switch on \LaTeX3 syntax. The difference with the default definition
of \gls{glsmakefirstuc} is that it prevents its argument from being
expanded.

\backmatter
\printterms
\printsummary
\printuserguideindex

\end{document}