1

I find myself creating new commands for latex commands that I commonly use in order to cut down on the cognitive load of what I am writing.

An example would be writing matrices, instead of writing the full command, I can simplify it to something like this

\newcommand\mat[1]{\begin{bmatrix}#1\end{bmatrix}}

As the amount of redefined commands increases, I began to wonder if other people have already done what I'm attempting to do, or how I could make it so others can benefit from my commands I'm creating.

I guess what I'm describing is maybe a package? But I have no experience making packages before and do not know what would go into this. The purpose of my package would be to reduce the amount of characters necessary to type mathematical commands and to reduce the cognitive load while writing latex.

If anyone could point me in the best direction for this question, it would be greatly appreciated.

cuppajoeman
  • 155
  • 6
    Welcome to TeX-SE! Yes, many people have done what you are about to do, and after a while they realized that it is really bad practice. At the very moment you share your files with others you will understand why. Everyone comes up with their own macros, and it becomes a real mess. Nowadays all editors allow you to implement short cuts, so if you want to have an abbreviation for matrix, teach your editor a new short cut. –  Jun 14 '19 at 17:10
  • Thanks for the welcome! To your first point I pose a question, maybe I have lots of macros that coincide with my friend's macros, but maybe there are some he doesn't have and that would be useful. Maybe my macros could still be of use, and maybe in some other form than a package? To your second point, I am using vim-tex and I have tons of macros for math already, my goal would to be to make it more clear to myself while writing and looking back at past documents and to reduce the amount of thinking I have to do. So a combination of editor shortcuts and macros ... Thanks for your reply @marmot – cuppajoeman Jun 14 '19 at 17:38
  • 2
    “Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.” ― Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship. Deviating from standard LaTeX syntax can have serious consequences on collaboration, error messages, code highlighting in editors, besides the cognitive load of learning a parallel language. ... – AboAmmar Jun 14 '19 at 18:32
  • ... That said, there are still packages that do this like the physics package which may be quite useful for physicists, but for general users it may not. – AboAmmar Jun 14 '19 at 18:33
  • Ok, sounds like the best way to go is to just define my own editor shortcuts. I appreciate the input @AboAmmar. – cuppajoeman Jun 14 '19 at 19:34
  • 1
    for your own use making a package is better than copying the definitions from document to document, that is easy to do just put them in a file mystuff.sty and then use \usepackage{mystuff} you can then see if anyone else wants to try them and make them available, but documenting to others how to use your macros is the hard part – David Carlisle Jun 14 '19 at 21:58
  • 1
    @AboAmmar Nooo! Don't recommend the physics package. It creates a lot more problems than it solves. – Henri Menke Jun 15 '19 at 02:48

1 Answers1

1

You seem to intend to add your own abbreviation-level in terms of a collection of (La)TeX macros to things that already exist.

On the one hand this might indeed make understanding the code of your documents more easy to you.

On the other hand this might complicate things in case of distributing your .tex source code so that other people can compile it:

Although this might make understanding the code more easy to you, it is not ensured that it will make understanding the code more easy to other people as other people may probably not be used to your macros.

Besides this, this might result in problems with some of the programs available for deriving/rendering .html-files and the like directly from your (La)TeX code. (E.g., TeX4ht, LaTeX2HTML, TtH, plasTeX, hyperlatex, ... )

Maybe adding your 'private level of abbreviation' can be done not on the level of (La)TeX macros but by means of editor-macros which let you type some abbreviations for inserting larger portions of (La)TeX code into the .tex-file.
Of course a disadvantage of this will be that with abbreviating during typing you usually are bound to those machines where the editing software is customizable in your ways and where you have possibilities and sufficient rights for importing your private customizations for the editing software.
If you work on many different computers, hereby using a diversity of different text editing programs, probably not all of the machines under your administration, binding your workflow to specific editing software by means of editor-macros just for that specific editing-software might not be a feasible approach.

Be that as it may.

Even without the desire of just typing less and making reading/understanding the code more easy, you can quickly get to a point where you cannot avoid writing (La)TeX-macros because you need functionality which is not available yet.

Therefore:

If you decide to supply your own set of LaTeX macros, it might be a good idea to provide everything within a single package.

There is the so called .dtx-format.

Like .sty files and .tex files .dtx files actually are just text files containing (La)TeX code.

The file name extension ".dtx" is an acronym for "Documented LaTeX source".

The .dtx format lets you maintain your code, user manual and comments for explaining the code within a single text file whose file name extension is .dtx .

From .dtx-files one can easily derive both .sty files which can be loaded via \usepackage and .pdf-files which contain the nicely formatted user manual and/or the nicely formatted commented source code of the package.

The source code of the LaTeX 2e kernel itself is maintained in .dtx format.

Many of the LaTeX packages submitted to the Comprehensive TeX Archive Network (CTAN) are managed in .dtx format.

In short:

The .dtx format lets you write (and compile a nicely looking .pdf-file thereof) the commented source code and the manuals for your package using the means of the package doc, and lets you generate files like the .sty-file (which is to be loaded via \usepackage) by means of the package docstrip.

You can realize the "generating-part" either by having (La)TeX load docstrip and carrying out so-called \generate-directives from within the .dtx file in question itself or by putting directives for loading docstrip and carrying out the \generate-directives into a separate plain text file whose file name extension then should be .ins .

Some CTAN-resources of interest might be:

clsguide – Documentation of LaTeX class and package writing

Description on CTAN:

Doc­u­men­ta­tion of com­mands (other than font-han­dling com­mands) that are use­ful when writ­ing a LaTeX class or pack­age.

Part of a set of doc­u­men­ta­tion that also cov­ers new LaTeX 2e com­mands, font-han­dling, type­set­ting Cyril­lic, LaTeX font en­cod­ings, con­fig­u­ra­tion op­tions and mod­i­fi­ca­tion of LaTeX.

doc – Format LaTeX documentation

Description on CTAN:

The pack­age pro­vides def­i­ni­tions that are nec­es­sary to for­mat the doc­u­men­ta­tion of LaTeX ker­nel and pack­age source files (Lit­er­ate LaTeX), which in­cor­po­rate both the doc­u­men­ta­tion and the code.

This pack­age is part of the LaTeX dis­tri­bu­tion.

Package documentation:
Frank Mitelbach: The doc and shortvrb Packages

docstrip – Remove comments from file

Description on CTAN:

The pack­age pre­pares a LaTeX ker­nel or pack­age source file for ac­tual use, by re­mov­ing the doc­u­men­ta­tion and meta-data. The pack­age can con­di­tion­ally in­clude parts of the source file, gen­er­ate many files from a sin­gle source, and gen­er­ate a sin­gle out­put from sev­eral source files.

The pack­age is part of the LaTeX dis­tri­bu­tion.

Package documentation:
Frank Mittelbach, Denys Duchier, Johannes Braams, Marcin Woliński, Mark Wooding: The DocStrip program

Scott Pakin: How to Package Your LaTeX Package

The abstract says:

This tutorial is intended for advanced LaTeX 2ε users who want to learn how to create .ins and .dtx files for distributing their homebrewed classes and style files.

DTX gallery – A small collection of minimal DTX examples

Description on CTAN:

A col­lec­tion of files that demon­strate sim­ple things that are pos­si­ble with the flex­i­ble and un­der-ap­pre­ci­ated doc­strip file for­mat. Each file of the collec­tion is pro­vided as a .dtx file and as the cor­re­spond­ing .pdf.

The set is in­tended as a com­pan­ion to Scott Pakin’s ex­cel­lent and in­flu­en­tial dtx­tut ex­am­ple of pro­duc­ing LaTeX pack­ages in this way.

In case you some day intend to publish packages by submitting them to the Comprehensive TeX Archive Network (CTAN), the following might be of interest:

How can I up­load a pack­age?

Ad­di­tional In­for­ma­tion for CTAN Upload­ers

Guidelines for uploading TDS-Packaged materials to CTAN

TeX Live package contributions

Ulrich Diez
  • 28,770