Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/larryv/mkvimball-sh

A portable Bourne utility for creating vimball archives
https://github.com/larryv/mkvimball-sh

bourne-shell shell vim vimball

Last synced: about 2 months ago
JSON representation

A portable Bourne utility for creating vimball archives

Awesome Lists containing this project

README 

          
////

.github/README.adoc

-------------------



SPDX-License-Identifier: CC0-1.0



Written in 2022-2023 by Lawrence Velázquez .



To the extent possible under law, the author has dedicated all copyright

and related and neighboring rights to this software to the public domain

worldwide.  This software is distributed without any warranty.



You should have received a copy of the CC0 Public Domain Dedication

along with this software.  If not, see

.

////



= mkvimball-sh

:source-language: sh



:title-cc0: CC0 1.0 Universal Public Domain Dedication

ifdef::env-github[]

:link-cc0: link:../COPYING.txt

endif::[]

ifndef::env-github[]

:link-cc0: https://creativecommons.org/publicdomain/zero/1.0/

:title-cc0: Creative Commons - {title-cc0}

endif::[]

:title-posix: POSIX.1-2017

:url-drchip: https://www.drchip.org/astronaut

:url-posix: https://pubs.opengroup.org/onlinepubs/9699919799



This is a

{link-cc0}[public-domain, title={title-cc0}]

rewrite of Charles E. Campbell's

`{url-drchip}/src/index.html#MKVIMBALL[mkvimball]`

utility for creating

{url-drchip}/vim/index.html#VIMBALL[vimball]

archives.  Written in portable Bourne shell, it can serve as

a replacement for noninteractive uses on a wide range of Unix and

Unix-like systems.  A shim is available for drop-in compatibility with

`mkvimball`.



// TODO: List some reasons why this is better than the original.



== Requirements



* A relatively recent Bourne or Bourne-compatible (including

{url-posix}/utilities/V3_chap02.html[POSIX-conformant,

title="{title-posix} - Volume 3, Chapter 2 ('Shell Command Language')"])

shell, available at `/bin/sh`.



* The typical Unix utilities, plus a couple that could be considered

atypical:

+

--

** `{url-posix}/utilities/m4.html[m4,

title="{title-posix} - Volume 3, Chapter 4 ('Utilities - m4')"]`

for creating the compatibility shim.

** `{url-posix}/utilities/make.html[make,

title="{title-posix} - Volume 3, Chapter 4 ('Utilities - make')"]`

for installation.

--

+

{url-posix}/utilities/V3_chap04.html[POSIX conformance,

title="{title-posix} - Volume 3, Chapter 4 ('Utilities')"]

is ideal, but minor transgressions are fine.



* https://www.shellcheck.net[ShellCheck] for optional testing.



* https://asciidoctor.org[Asciidoctor] for regenerating the manual

pages.  Only necessary if modifying the documentation source.



== Installation, etc.



To install/uninstall the `mkvimball-sh` utility to/from `/usr/local`

(privileges required, presumably):



[source]

cd /path/to/this/repo && make install



[source]

cd /path/to/this/repo && make uninstall



To avoid overwriting the original `mkvimball`, the standard targets omit

the compatibility shim, which is also named `mkvimball`.  To install

both `mkvimball-sh` and the shim:



[source]

cd /path/to/this/repo && make installshim



To uninstall the shim (but not `mkvimball-sh`):



[source]

cd /path/to/this/repo && make uninstallshim



:title-gmake-man: GNU Make Manual

:title-gmake-man-cmdvars: {title-gmake-man} - \

    Variables for Specifying Commands

:title-gmake-man-dirvars: {title-gmake-man} - \

    Variables for Installation Directories

:url-gmake-man: https://www.gnu.org/software/make/manual/html_node

:url-gmake-man-cmdvars: {url-gmake-man}/Command-Variables.html

:url-gmake-man-dirvars: {url-gmake-man}/Directory-Variables.html



To use an installation prefix other than `/usr/local`, define the

`{url-gmake-man-dirvars}#index-prefix[prefix,

title={title-gmake-man-dirvars} - 'prefix']`

macro when invoking `make`.  For example:



[source]

cd /path/to/this/repo && make prefix=/opt installshim



[source]

cd /path/to/this/repo && make prefix=/opt uninstall uninstallshim



To run basic tests:



[source]

cd /path/to/this/repo && make check



The

`{url-gmake-man-dirvars}#index-bindir[bindir,

title={title-gmake-man-dirvars} - 'bindir']`,

`{url-gmake-man-dirvars}[datarootdir,

title={title-gmake-man-dirvars}]`,

`{url-gmake-man-dirvars}#index-exec_005fprefix[exec_prefix,

title={title-gmake-man-dirvars} - 'exec_prefix']`,

`{url-gmake-man-dirvars}[man1dir,

title={title-gmake-man-dirvars}]`,

and

`{url-gmake-man-dirvars}[mandir,

title={title-gmake-man-dirvars}]`

macros are supported for unorthodox installation hierarchies.  The

`{url-gmake-man}/DESTDIR.html[DESTDIR]`

macro is supported for staged installs.  The `ASCIIDOCTOR` (with

`ASCIIDOCTORFLAGS`),

`{url-gmake-man-cmdvars}[INSTALL,

title={title-gmake-man-cmdvars}]`,

`{url-gmake-man-cmdvars}[INSTALL_DATA,

title={title-gmake-man-cmdvars}]`,

`{url-gmake-man-cmdvars}[INSTALL_PROGRAM,

title={title-gmake-man-cmdvars}]`,

`M4` (with `M4FLAGS`),

and

`SHELLCHECK` (with `SHELLCHECKFLAGS`)

macros are supported for using alternate tools.



== Usage



[source]

mkvimball-sh [-a] [-f archive] [--] [file ...]



The `mkvimball-sh` utility copies the contents of its input

{url-posix}/basedefs/V1_chap03.html#tag_03_403[text files,

title="{title-posix} - Volume 1, Chapter 3, Section 403 ('Text File')"]

to a vimball archive.  The input files can be specified as _file_

operands or as a list of LF-terminated paths on standard input.  The

archive is written to standard output or, if `-f` is specified, to

_archive_.  If `-a` is specified, the archive header is omitted from the

output so it can be appended to an existing archive; if both `-a` and

`-f` are specified, _archive_ is appended to instead of overwritten.



[source]

mkvimball archivebase file ...



The `mkvimball` shim provides drop-in compatibility with the original

`mkvimball`.  It rejects _archivebase_ if it contains a "." character;

otherwise, it writes the archive to `__archivebase__.vba`.



Consult the xref:../mkvimball-sh.adoc[man page] for more details.



// TODO: Note some differences from the original?



== Legal



To the extent possible under law, the author has

{link-cc0}[dedicated, title={title-cc0}]

all copyright and related and neighboring rights to this software to the

public domain worldwide.  This software is published from the United

States of America and distributed without any warranty.



Refer to

ifdef::env-github[`link:../install-sh[install-sh]`]

ifndef::env-github[`install-sh`]

for its separate licensing terms.