1 \documentclass[letterpaper]{article}
2
3 \usepackage{noweb}
4
5 \usepackage{lmodern}
6
7 \usepackage[nottoc]{tocbibind}
8
9 \usepackage[
10 letterpaper,
11 portrait, left=0.94444in, top=1.22222in, bottom=2.44444in, right=1.88888in
12
13 ]{geometry}
14
15 \usepackage[colorlinks]{hyperref}
16
17 \setlength{\parindent}{0pt}
18 \setlength{\parskip}{\medskipamount}
19
20
21 \begin{document}
22
23
24
25 \title{vim-noweb -- extend Vim to support Noweb}
26 \author{Edward McGuire}
27 \date{\today}
28 \maketitle
29
30 \begin{abstract}
31
32 \texttt{vim-noweb.nw} is the source file for a Vim plugin that adds support for
33 Noweb \texttt{.nw} source file editing, such as syntax highlighting.
34 Within \texttt{.nw} files, documentation chunks get \TeX{} syntax highlighting.
35 Code chunks get the syntax highlighting of the code language, if it can be
36 identified.
37 Otherwise they get a generic “String” highlighting.
38
39 New languages can be added easily by passing a language name, filename pattern,
40 and syntax file name to a registration function.
41
42 \end{abstract}
43
44
45
46 \newpage
47 Copyright © 2023, 2024 Edward K. McGuire, Fort Worth, Texas. All rights reserved.
48 Redistribution and use of this software, with or without modification, is
49 permitted, provided that the following conditions are met:
50
51 1. Redistribution of this software must retain the copyright notice above, this
52 list of conditions, and the disclaimer below.
53
54 THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS OR IMPLIED
55 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
56 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
57 SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
58 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
59 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA OR PROFITS; OR BUSINESS
60 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
61 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCY OR OTHERWISE) ARISING
62 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
63 OF SUCH DAMAGE.
64
65
66
67 \newpage \tableofcontents
68
69
70
71 \newpage \section{Overview}
72
73 The \emph{vim-noweb} package is four files: a file type detection Vim script, a
74 syntax highlighting Vim script, a \texttt{README}, and a \texttt{LICENSE}, saved
75 to a tarball.
76 The package is compiled from the source file \texttt{vim-noweb.nw} using
77 \emph{Noweb} and \emph{make}.
78 The finished product can be found at
79 << url>>=
80 https://metaed.com/papers/vim-noweb/
81 @
82 The package development environment is Slackware64 Linux, release 15.0.
83
84 <<makefile>>=
85
86
87
88
89 usage ::
90 @echo 'makefile: usage:'
91 @echo ' make all'
92 @echo ' make install (implies all)'
93 @echo ' make package (implies install)'
94 @echo ' make website (implies package)'
95 @echo ' make commit'
96 @echo ' make clean'
97 all ::
98 install :: all
99 package :: install
100 website :: package
101 commit ::
102 git commit -av -uno
103 clean ::
104 rm -f *~ .*~
105 @
106
107
108
109 \newpage \section{Filetype detection}
110
111 The filetype detection file \texttt{ftdetect-noweb.vim} identifies \emph{Noweb}
112 source files by the filename suffix \texttt{.nw}.
113 Its name in the bundle is \texttt{ftdetect/noweb.vim}.
114
115 <<ftdetect-noweb.vim>>=
116 " <<boilerplate 1>>
117 " <<boilerplate 2>>
118 " <<boilerplate 3>>
119 " <<boilerplate 4>>
120 @
121
122 <<makefile>>=
123 all :: ftdetect-noweb.vim
124 install :: ~/.vim/ftdetect/noweb.vim
125 ~/.vim/ftdetect/noweb.vim : ftdetect-noweb.vim
126 mkdir -p ~/.vim/ftdetect && cp $< $@
127 ftdetect-noweb.vim : vim-noweb.nw.sentinel ;
128 clean ::
129 rm -f ftdetect-noweb.vim
130 @
131
132 Detection is enabled by a single-line declaration that the filename pattern
133 \texttt{*.nw} identifies a file of type \texttt{noweb}.
134
135 <<ftdetect-noweb.vim>>=
136 autocmd BufNewFile,BufRead *.nw set filetype=noweb
137 @
138
139
140
141 \newpage \section{Syntax highlighting}
142
143 \texttt{syntax-noweb.vim} contains syntax highlighting directives for
144 \emph{Noweb} source files.
145 Its name in the bundle is \texttt{syntax/noweb.vim}.
146
147 <<syntax-noweb.vim>>=
148 " <<boilerplate 1>>
149 " <<boilerplate 2>>
150 " <<boilerplate 3>>
151 " <<boilerplate 4>>
152 @
153
154 <<makefile>>=
155 all :: syntax-noweb.vim
156 install :: ~/.vim/syntax/noweb.vim
157 ~/.vim/syntax/noweb.vim : syntax-noweb.vim
158 mkdir -p ~/.vim/syntax && cp $< $@
159 syntax-noweb.vim : vim-noweb.nw.sentinel ;
160 clean ::
161 rm -f syntax-noweb.vim
162 @
163
164 The stock \TeX{} syntax file \texttt{tex.vim} is used to syntax-highlight
165 everything outside code chunks.
166
167 \begin{quote}
168 \textbf{NOTE:}
169 All regular expressions below use the \emph{Vim} “very magic” syntax.
170 This is done by prefixing each expression with \texttt{\textbackslash{}v}.
171 \end{quote}
172
173 \begin{quote}
174 \textbf{NOTE:}
175 According to \texttt{syn-pattern} in the manual, syntax patterns are always
176 interpreted like the \texttt{magic} option is set, no matter what the actual
177 value of \texttt{magic} is.
178 Hence the “very magic” prefix is always an override of “magic”.
179 I prefer “very magic” for its readability, and for its similarity to Extended
180 Regular Expressions.
181 Using “very magic”, there is no need to escape parentheses (grouping), vertical
182 line (alternation), or braces (repetition).
183 But maybe “magic” would be easier for other \textit{Vim} programmers to read.
184 \end{quote}
185
186 <<syntax-noweb.vim>>=
187 if exists("b:current_syntax") | finish | endif
188 syntax include @SyntaxTeX syntax/tex.vim
189 unlet b:current_syntax
190 syntax region Normal start=/\v%^/ end=/\v%$/ contains=@SyntaxTeX
191 @ %def SyntaxTex
192
193 \emph{Noweb} syntax highlighting is declared as extensions to the \TeX{} syntax.
194
195 <<syntax-noweb.vim>>=
196 <<syntax-noweb.vim recognition>>
197 <<syntax-noweb.vim doc chunk>>
198 <<syntax-noweb.vim quote>>
199 <<syntax-noweb.vim code chunk>>
200 <<syntax-noweb.vim code use>>
201 @
202
203 The syntax file ends by setting the \texttt{current\_syntax} variable in buffer
204 scope.
205
206 <<syntax-noweb.vim>>=
207 let b:current_syntax = "noweb"
208 @
209
210 The \emph{Noweb} syntax is described partly in the manual, partly in the source.
211 Some notable quotations that were helpful in writing this syntax file:
212
213 \begin{itemize}
214
215 \item “A module name is any text enclosed in double angle brackets.”
216
217 \item “Double angle brackets may be escaped in source by preceding them
218 with the at sign.”
219
220 \item “No other character, not even the at sign, needs to be escaped [in
221 source].”
222
223 \item “A module definition is a module name, followed by one equals
224 sign, possibly followed by white space, on a line by itself.”
225
226 \end{itemize}
227
228 “Test” subsections below are used to check highlighting.
229 Install the plugin and then open the file \texttt{vim-noweb.nw} in \emph{Vim}.
230
231
232
233 \newpage \subsection{Documentation chunk directive}
234
235 A documentation chunk is introduced by a single at-sign.
236 Indexing or plain documentation can follow.
237
238 <<syntax-noweb.vim doc chunk>>=
239 syntax match PreProc "\v^[@]($| [%]def .*| )" containedin=@SyntaxTeX
240 @
241
242 \subsubsection{Test}
243
244 @
245 @ %def test1 test2
246 @ plain documentation
247
248
249
250 \newpage \subsection{Quoted code in documentation}
251
252 Double square brackets bracket a code quotation within a documentation chunk.
253 It can span lines.
254 It can contain code uses.
255 It can contain nested quotes.
256 A preceding at-sign (@) escapes quoting.
257 The language cannot be determined, so plain String highlighting is used.
258
259 <<syntax-noweb.vim quote>>=
260 syntax region nowebCodeQuotation matchgroup=Operator
261 \ start="\v[@]@<!\[\["
262 \ end="\v\]\]"
263 \ containedin=@SyntaxTeX
264 \ contains=nowebCodeUse,nowebCodeQuotation
265 highlight link nowebCodeQuotation String
266 @ %def nowebCodeQuotation
267
268 \subsubsection{Test}
269
270 [[
271 CODE QUOTATION
272 CODE USE WITHIN CODE QUOTATION
273 <<code use>>
274 [[NESTED CODE QUOTATION]]
275 ]]
276
277
278
279 \newpage \subsection{Generic code-chunk declaration and body}
280
281 A code chunk declaration is introduced by name in double angle brackets followed
282 by equals-sign and optional trailing whitespace.
283 The name can contain code quotations.
284 The code body begins on the next line.
285
286 A code-chunk body is terminated by a new doc or code chunk introducer.
287 It can span lines.
288 It can contain code uses.
289
290 Generic syntax is defined first so that specific syntaxes override it.
291 Like code quotations, it is given plain String highlighting.
292
293 <<syntax-noweb.vim code chunk>>=
294 syntax match nowebCodeChunkDecl "\v^[<][<].*[>][>][=][ \t]*$"
295 \ skipnl
296 \ containedin=@SyntaxTeX
297 \ contains=nowebCodeQuotation
298 \ nextgroup=nowebCodeChunkBody
299 highlight link nowebCodeChunkDecl PreProc
300 syntax region nowebCodeChunkBody
301 \ start="\v.*"
302 \ end="\v^([@]($| ))|([<][<].*[>][>][=][ \t]*$)"me=s-1
303 \ contained
304 \ contains=nowebCodeUse
305 highlight link nowebCodeChunkBody String
306 @ %def nowebCodeChunkDecl nowebCodeChunkBody
307
308 \subsubsection{Test}
309
310 <<test generic syntax>>=
311 This is a sample generic syntax code chunk.
312 @
313
314 <<test [[with code quotation]] generic syntax>>=
315 This is a sample generic syntax code chunk.
316 @
317
318
319
320 \newpage \subsection{Language-specific code chunk declaration and body}
321
322 Credit for this technique goes to the developers of the \emph{Ant} syntax file
323 \texttt{ant.vim} distributed with \emph{Vim}.
324
325 <<syntax-noweb.vim recognition>>=
326 function NowebRecognize( language, pattern, file )
327 execute 'syntax match nowebCodeChunkDecl' . a:language
328 \ . ' "\v^[<][<]' . a:pattern . '[>][>][=]\s*$"'
329 \ . ' skipnl'
330 \ . ' containedin=@SyntaxTeX'
331 \ . ' contains=nowebCodeQuotation'
332 \ . ' nextgroup=nowebCodeChunkBody' . a:language
333 execute 'highlight link nowebCodeChunkDecl' . a:language . ' PreProc'
334 execute 'syntax include @Syntax' . a:language . ' syntax/' . a:file
335 execute 'unlet b:current_syntax'
336 execute 'syntax region nowebCodeChunkBody' . a:language
337 \ . ' keepend'
338 \ . ' start="\v.*"'
339 \ . ' end="\v^([@]($| ))|([<][<].*[>][>][=][ \t]*$)"me=s-1'
340 \ . ' contained'
341 \ . ' contains=nowebCodeUse,@Syntax' . a:language
342 endfunction
343 @ %def nowebRecognize
344
345 This is the list of languages currently set up to be recognized and
346 syntax-highlighted using a stock syntax file.
347
348 <<syntax-noweb.vim code chunk>>=
349 call NowebRecognize( 'Awk' , '.*\.awk(|\s.*)' , 'awk.vim' )
350 call NowebRecognize( 'Bash' , '.*\.bash(|\s.*)' , 'bash.vim' )
351 call NowebRecognize( 'Crontab' , '.*\.crontab(|\s.*)' , 'crontab.vim' )
352 call NowebRecognize( 'Gnuplot' , '.*\.gp(|\s.*)' , 'gnuplot.vim' )
353 call NowebRecognize( 'Make' , '[mM]akefile(|\s.*)' , 'make.vim' )
354 call NowebRecognize( 'Man' , '.*\.[18](|\s.*)' , 'man.vim' )
355 call NowebRecognize( 'Python' , '.*\.py(|\s.*)' , 'python.vim' )
356 call NowebRecognize( 'Sed' , '.*\.sed(|\s.*)' , 'sed.vim' )
357 call NowebRecognize( 'Sh' , '.*\.sh(|\s.*)' , 'sh.vim' )
358 @
359
360 Some stock syntaxes use the \texttt{extend} keyword when they define a region.
361 It can cause their syntax highlighting to leak out past the end of a code block,
362 because it overrides the \texttt{keepend} keyword.
363 I have tested stock syntaxs that use \texttt{extend} to see if they leak.
364 Those that do are not enabled by default.
365 The local system operator will have to enable them manually.
366 The following syntaxes are disabled for that reason:
367
368 <<syntax-noweb.vim code chunk>>=
369 " call NowebRecognize( 'C' , '.*\.c(|\s.*)' , 'c.vim' )
370 " call NowebRecognize( 'Perl' , '.*\.pl(|\s.*)' , 'perl.vim' )
371 " call NowebRecognize( 'Vim' , '.*\.vim(|\s.*)' , 'vim.vim' )
372 @
373
374 \subsubsection{Test}
375
376 <<makefile example>>=
377 target :: dependency ; action
378 @
379
380 <<makefile [[with quoting]] example>>=
381 target :: dependency ; action
382 @
383
384 <<not makefile counterexample>>=
385 target :: dependency ; action
386 @
387
388 <<makefile.c counterexample>>=
389 target :: dependency ; action
390 @
391
392 <<example .vim>>=
393 unlet recognition
394 @
395
396 <<example .vim [[with quoting]]>>=
397 unlet recognition
398 @
399
400 <<counterexample .vi>>=
401 unlet recognition
402 @
403
404 <<example try.pl>>=
405 use strict ;
406 @
407
408 <<example try.pl [[with quoting]]>>=
409 use strict ;
410 @
411
412 <<counterexample try.pli>>=
413 use strict ;
414 @
415
416 <<example try.c>>=
417 main() { return ; }
418 @
419
420 <<example try.c [[with quoting]]>>=
421 main() { return ; }
422 @
423
424 <<counterexample try.cpp>>=
425 main() { return ; }
426 @
427
428 <<example try.sh>>=
429 echo hello world
430 @
431
432 <<example try.sh [[with quoting]]>>=
433 echo hello world
434 @
435
436 <<counterexample try.shm>>=
437 echo hello world
438 @
439
440 <<example try.pl that demonstrates a leak out of the code block>>=
441 /*
442 @
443
444 <<example try.c that demonstrates a leak out of the code block>>=
445 /*
446 @
447
448 <<example try.py>>=
449
450 import sys
451 hello_text = "hello, world"
452 def hello_function():
453 print( hello_text )
454 hello_function()
455 sys.exit(0)
456
457 """
458 multiline string used as a comment
459 """
460
461 """
462 unterminated multiline string to test for leak out of the code block
463 @
464
465
466
467 \newpage \subsection{Code use}
468
469 Double angle brackets bracket a code use within a code chunk.
470 It cannot span lines.
471 When used more than once on a line, the closest close-brackets end a code use.
472 It can contain quotes.
473 A preceding at-sign (@) escapes a code use.
474
475 <<syntax-noweb.vim code use>>=
476 syntax match nowebCodeUse "\v[@]@<![<][<].{-}[>][>]"
477 \ contained
478 \ contains=nowebCodeQuotation
479 highlight link nowebCodeUse Identifier
480 @ %def nowebCodeUse
481
482 \subsubsection{Test}
483
484 <<code use test inner block>>=
485 CODE TEST BODY
486 <<code use test outer block>>=
487 123
488 <<code use test inner block>>
489 456
490 @
491
492 <<code use test inner block 2>>=
493 CODE TEST BODY
494 <<code use test outer block 2>>=
495 123<<code use test inner block 2>>456
496 @
497
498
499
500 \newpage \section{Compiling the developer manual, makefile, and sentinel file}
501
502 <<makefile>>=
503 all :: vim-noweb.pdf
504 vim-noweb.pdf : vim-noweb.tex
505 latexmk -pdf vim-noweb
506 clean ::
507 latexmk -C vim-noweb
508 vim-noweb.tex : vim-noweb.nw.sentinel ;
509 clean ::
510 rm -f vim-noweb.tex
511 @
512
513 <<makefile>>=
514 all :: makefile
515 makefile : vim-noweb.nw.sentinel ;
516 clean ::
517 rm -f makefile
518 @
519
520 <<makefile>>=
521 vim-noweb.nw.sentinel : vim-noweb.nw
522 noweb $<
523 @
524
525
526
527 \newpage \section{Compiling the plugin package}
528
529 <<makefile>>=
530 TMPDIR = /tmp
531 PKGDIR = noweb
532 PKG = $(TMPDIR)/$(PKGDIR)
533 package :: vim-noweb.tgz
534 vim-noweb.tgz : README LICENSE ftdetect-noweb.vim syntax-noweb.vim
535 rm -rf $(PKG)
536 mkdir -p $(PKG)/{ftdetect,syntax}
537 cp README LICENSE $(PKG)/
538 cp ftdetect-noweb.vim $(PKG)/ftdetect/noweb.vim
539 cp syntax-noweb.vim $(PKG)/syntax/noweb.vim
540 ( cd $(TMPDIR) && tar cf - $(PKGDIR) | gzip -9 ) > $@
541 @
542
543 <<README>>=
544 Vim plugin for Noweb (.nw) files
545
546 vim-noweb is a Vim plugin that adds support for Noweb source file editing, such
547 as syntax highlighting.
548
549 TeX syntax highlighting is applied to documentation chunks.
550
551 Syntax highlighting applied to code chunks is that of the code language, if it
552 can be identified.
553
554 More information and support:
555 << url>>
556 https://www.reddit.com/r/LitProg/
557 @
558
559 <<makefile>>=
560 README : vim-noweb.nw.sentinel ;
561 clean ::
562 rm -f README
563 @
564
565 <<LICENSE>>=
566 Copyright © 2023, 2024 Edward K. McGuire, Fort Worth, Texas. All rights reserved.
567 Redistribution and use of this software, with or without modification, is
568 permitted, provided that the following conditions are met:
569
570 1. Redistribution of this software must retain the copyright notice above, this
571 list of conditions, and the disclaimer below.
572
573 THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS OR IMPLIED
574 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
575 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
576 SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
577 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
578 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA OR PROFITS; OR BUSINESS
579 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
580 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCY OR OTHERWISE) ARISING
581 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
582 OF SUCH DAMAGE.
583 @
584
585 <<makefile>>=
586 LICENSE : vim-noweb.nw.sentinel ;
587 clean ::
588 rm -f LICENSE
589 @
590
591
592
593 \newpage \section{Compiling the plugin website}
594
595 << html>>=
596 /var/www/metaed.com/root/papers/vim-noweb
597 <<makefile>>=
598 all :: header.html footer.html htaccess
599 header.html footer.html htaccess : vim-noweb.nw.sentinel ;
600 clean ::
601 rm -f header.html footer.html htaccess
602 website :: << html>>/header.html
603 website :: << html>>/footer.html
604 website :: << html>>/.htaccess
605 website :: << html>>/vim-noweb.pdf
606 website :: << html>>/vim-noweb.nw
607 website :: << html>>/vim-noweb.html
608 website :: << html>>/vim-noweb.tgz
609 << html>> : ; mkdir -p $@
610 << html>>/header.html : << html>> header.html ; cp header.html $@
611 << html>>/footer.html : << html>> footer.html ; cp footer.html $@
612 << html>>/.htaccess : << html>> htaccess ; cp htaccess $@
613 << html>>/vim-noweb.pdf : << html>> vim-noweb.pdf ; cp vim-noweb.pdf $@
614 << html>>/vim-noweb.nw : << html>> vim-noweb.nw ; cp vim-noweb.nw $@
615 << html>>/vim-noweb.html : << html>> vim-noweb.nw.html ; cp vim-noweb.nw.html $@
616 << html>>/vim-noweb.tgz : << html>> vim-noweb.tgz ; cp vim-noweb.tgz $@
617 vim-noweb.nw.html : vim-noweb.nw
618 vim -c 'set noundofile' -c TOhtml -c wqa $<
619 clean ::
620 rm -f vim-noweb.nw.html
621 @
622 @
623
624 <<header.html>>=
625 <!-- <<boilerplate 1>> -->
626 <!-- <<boilerplate 2>> -->
627 <!-- <<boilerplate 3>> -->
628 <!-- <<boilerplate 4>> -->
629 <h1> << url>> </h1>
630 <p>
631 This is the home of <code>vim-noweb</code>, a Vim syntax highlighting plugin for
632 Noweb source files.
633 @
634
635 <<footer.html>>=
636 <!-- <<boilerplate 1>> -->
637 <!-- <<boilerplate 2>> -->
638 <!-- <<boilerplate 3>> -->
639 <!-- <<boilerplate 4>> -->
640 <p>
641 Copyright © 2023, 2024 Edward K. McGuire, Fort Worth, Texas. All rights reserved.
642 Redistribution and use of this software, with or without modification, is
643 permitted, provided that the following conditions are met:
644 <p>
645 1. Redistribution of this software must retain the copyright notice above, this
646 list of conditions, and the disclaimer below.
647 <p>
648 THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS OR IMPLIED
649 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
650 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
651 SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
652 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
653 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA OR PROFITS; OR BUSINESS
654 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
655 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCY OR OTHERWISE) ARISING
656 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
657 OF SUCH DAMAGE.
658 @
659
660 <<htaccess>>=
661 # This file is part of the vim-noweb package.
662 # Copyright (c) 2023, 2024 Edward K. McGuire.
663 # It was compiled from vim-noweb.nw using Norman Ramsey's Noweb.
664 <IfModule autoindex_module>
665 Options +Indexes
666 HeaderName header
667 ReadmeName footer
668 IndexOptions FancyIndexing
669 IndexOptions +IgnoreClient
670 IndexOptions +VersionSort
671 IndexOptions +Charset=UTF-8
672 IndexOptions +NameWidth=* DescriptionWidth=*
673 # Ignore hidden files. The syntax of IndexOptions filename patterns makes it
674 # impossible to ignore two-character hidden files without also ignoring ..
675 # (parent directory), so we ignore three-character hidden files and longer.
676 IndexIgnore .??*
677 IndexIgnore *~
678 IndexIgnore header.html footer.html
679 AddDescription "Current technical paper (PDF)" vim-noweb.pdf
680 AddDescription "Current source (Noweb)" vim-noweb.nw
681 AddDescription "How source looks highlighted" vim-noweb.html
682 AddDescription "Current plugin (compressed tar)" vim-noweb.tgz
683 </IfModule>
684 @
685
686
687
688 \newpage \section{Boilerplate}
689
690 The comment lines below appear at the top of each text file in the distribution.
691
692 <<boilerplate 1>>=
693 This file is part of the vim-noweb package.
694 <<boilerplate 2>>=
695 Copyright (c) 2023, 2024 Edward K. McGuire.
696 <<boilerplate 3>>=
697 It was compiled from vim-noweb.nw using Norman Ramsey's Noweb.
698 <<boilerplate 4>>=
699 Last commit $Date: Fri Oct 13 20:23:21 2023 +0000 $
700 @
701
702
703
704 \newpage \section{Roadmap}
705
706 It was suggested in a general way here
707 \url{https://news.ycombinator.com/item?id=35960743}
708 that it would be useful for a LitProg syntax highlighter to easily gray out code
709 chunks, or documentation chunks. Consider for a future release.
710
711 While I’m at it, folding should be really easy and would make a great addition.
712
713
714
715 \newpage \section{Notes on packagemaking}
716
717 These are notes on how to distribute a Vim plugin as a package.
718
719 \subsection{Source 1: Vim documentation}
720
721 <<to clean up>>=
722 Vim Reference Manual, Chapter 26, "Repeating commands, Vim scripts and
723 debugging", section 6, "Creating Vim packages" and section 6, "Using Vim
724 packages".
725
726 Distribute as an archive, or distribute from a repository.
727 "An archive can be used by more users, but is harder to update to a new
728 version."
729 "A repository can usually be kept up-to-date easiy, but it requires a program
730 like 'git' to be available."
731 "You can do both, github can automatically create an archive for a release."
732
733 Directory layout example
734
735 start/foobar/plugin/foo.vim " always loaded, defines commands
736 start/foobar/plugin/bar.vim " always loaded, defines commands
737 start/foobar/autoload/foo.vim " loaded when foo command used
738 start/foobar/doc/foo.txt " help for foo.vim
739 start/foobar/doc/tags " help tags
740 opt/fooextra/plugin/extra.vim " optional plugin, defines commands
741 opt/fooextra/autoload/extra.vim " loaded when extra command used
742 opt/fooextra/doc/extra.txt " help for extra.vim
743 opt/fooextra/doc/tags " help tags
744
745 This allows for the user to do: >
746 mkdir ~/.vim/pack/myfoobar
747 cd ~/.vim/pack/myfoobar
748 git clone https://github.com/you/foobar.git
749
750 Here "myfoobar" is a name that the user can choose, the only condition is that
751 it differs from other packages.
752
753
754 In your documentation you explain what the plugins do, and tell the user how
755 to load the optional plugin: >
756 :packadd! fooextra
757
758 You could add this packadd command in one of your plugins, to be executed when
759 the optional plugin is needed.
760
761 Run the `:helptags` command to generate the doc/tags file. Including this
762 generated file in the package means that the user can drop the package in his
763 pack directory and the help command works right away. Don't forget to re-run
764 the command after changing the plugin help: >
765 :helptags path/start/foobar/doc
766 :helptags path/opt/fooextra/doc
767
768 Vim startup supports packages, which are collections of plugins.
769 It looks for the "pack" directory in all the places in "packpath". It
770 scans "pack/*/start" for plugins. And, Vim also supports optional plugins found
771 in "pack/*/opt".
772 pack/ where to find packages
773 pack/a
774 pack/b
775 pack/c named by local operator, these are installed packages
776 pack/a/start Vim finds this at startup and scans it for plugins
777 pack/b/start Vim finds this at startup and scans it for plugins
778 pack/c/start Vim finds this at startup and scans it for plugins
779
780 pack/x/opt is for manual loading -- :packadd pkgname will load the package from
781 pack/x/opt/pkgname
782
783 <https://dev.to/iggredible/how-to-use-vim-packages-3gil>
784 The user-part of the name is for the end-user to organize packages. Organization
785 can be anything from a monolith such as ".vim/pack/my", to an organization by
786 type of package
787 ~/.vim/pack/colors
788 ~/.vim/pack/syntax
789 ~/.vim/pack/objects
790 ~/.vim/pack/plugins
791
792
793 There are various package manager add-ons for Vim
794 pathogen
795 vundle
796 dein
797 vim-plug
798 vim-update-bundles
799 minpac
800
801 Matvey at vim\_use at Google Groups points out the "user-part" can be thought
802 of as "manager-name" and be used to avoid conflicts between multiple plugin
803 managers. So
804 ~/.vim/pack/pathogen/*
805 ~/.vim/pack/vundle/*
806 ~/.vim/pack/dein/*
807 ~/.vim/pack/vim-plug/*
808 ~/.vim/pack/manual/*
809
810 Pathogen is not recommended even by the developer for new users. The startup
811 search for "start" folders, and the :packadd search for "opt" folders, replaces
812 Pathogen.
813
814 Vundle can install and update plugins. Its Plugin command takes a URI and
815 automatically integrates with GitHub and with vim-scripts.org. Examples from the
816 Vundle manual:
817 Plugins with a slash in the name are grabbed from GitHub.
818 "VundleVim/Vundle.vim" => https://github.com/VundleVim/Vundle.vim
819 Plugins without a slash are grabbed from vim-scripts
820 "ctrlp.vim" => https://github.com/vim-scripts/ctrlp.vim
821 This is (was) a mirror on Github of the vim-scripts site, called "vim-scraper".
822 Vundle is described by the mirror author as an "early package manager", along
823 with Vim Update Bundles, and obsolete because Vim scripts are now developed on
824 Github and installable straight from source.
825 "Mostly it was created because vimballs are super duper unfriendly to package
826 managers."
827 --- https://vim-scraper.github.io/
828 This does not however address auto-updating.
829
830 dein -- active development has stopped. Only bug fixes will be made.
831
832 vim-plug - works a lot like Vundle. Has a "Plug" command that can grab a plugin
833 from Github or really any URL. Last updated very recently.
834
835 vim-update-bundles - end of life.
836
837 minpac - updates, but only supports Github URLs (and short form account/repo).
838 From its readme:
839 Similar projects
840 There are some other plugin managers built on top of the Vim 8's packages feature.
841 vim-packager: written in Vim script
842 pack: written in Rust
843 infect: written in Ruby
844 vim-pck: written in Python
845 vim8-pack: written in Bash
846 volt: written in Go
847 autopac: modified version of minpac
848 plugpac.vim: thin wrapper of minpac, provides vim-plug like experience
849 minPlug: written in Vim script
850
851 Vim also distributes with a plugin called the "Vimball Archiver", "vimball.vim".
852 See :help vimball
853 Vimball supports installing and removing plugins that are packaged as
854 "vimballs", analogous to "tarballs".
855 It also has a MkVimball command which builds a Vimball .vba file.
856 There is external documentation on automating this process using make.
857 [[http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27]]
858
859 vim.org has a place to upload scripts and packages.
860 This collection does not seem to be supported by package managers.
861
862 Vim documentation includes a Getscript plugin that seems to get latest versions
863 of installed scripts.
864 @
865
866
867
868 \end{document}