-
Notifications
You must be signed in to change notification settings - Fork 0
/
RandomPlaceHolder.tex
124 lines (101 loc) · 6.17 KB
/
RandomPlaceHolder.tex
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
\documentclass[12pt]{article}
\usepackage{preamble}
\usepackage{randomplaceholder}
\placeholderclean%
\placeholderinit{placeholderimage}
\title{randomplaceholder user manual}
\author{yaxinm}
\date{11 October 2022}
\begin{document}
\maketitle
Want to add bit of fun to your writing process?
Insert a random image into your article by typing \lstinline{\placeholder}.
\placeholder[][0.3\textwidth][A random figure.]
Project located at \url{https://github.com/yaxinm/RandomPlaceholder}.
\section{Supported platforms}
\textbf{Unix} systems and \textbf{Overleaf}, compiled with pdfLaTex.
\textit{Shell-escape must be enabled.} Shell commands are used to gather the list of images.
The package has been tested on Ubuntu 20.04 (x86\textunderscore64) and Overleaf.
Sadly, it doesn't work on \textbf{Windows} yet.
\section{Installation}
Installation is different for local \LaTeX~project or Overleaf.
\subsection{Install package for one project}
Use this method for \textbf{Overleaf}.
Copy the content of the folder \lstinline{randomplaceholder} into your project, place the \lstinline{.sty} right next to your \lstinline{main.tex}.
\subsection{Install package for all local projects}
Copy the folder \lstinline{randomplaceholder} into your TeX home directory. On linux, using the default, you should copy \lstinline{randomplaceholder} into the directory \lstinline{~/texmf/tex/latex/}.
You can find your TeX home with the command \lstinline{kpsewhich -var-value=TEXMFHOME}.
\section{How to use}
\subsection{Usepackage}
Add this line to the top of your file.
\begin{lstlisting}
\usepackage{randomplaceholder}
\end{lstlisting}
Now, prepare a folder full of fun images. Make sure that folder contains only images (any format) and the names of both the directory and the files follow the Unix naming conventions. For example, \lstinline{placeholderimage/} in this repo.
\subsection{Initialise}
Initialise the package by adding the following command at the top of your file.
\begin{lstlisting}
\placeholderinit{$YourImageFolder}
\end{lstlisting}
\lstinline{$YourImageFolder} is a valid path to a directory, no space between the \{, \} and the path is allowed.
By running \lstinline{\placeholderinit}, a file containing the macros will be created base on the content of \lstinline{$YourImageFolder}.
Once the macro file is present, \lstinline{\placeholderinit} will not overwrite it even if the content of \lstinline{$YourImageFolder} has changed or if you recompile.
To reinitiate, call \lstinline{\placeholderclean} before calling \lstinline{\placeholderinit}.
\subsubsection{Compatibility}
Not compatible with TeXLive~2021 or older.
If you want to use is with an incompatible version of \LaTeX, there is a workaround.
You can generate the required \lstinline{placeholdermacros.tmp} manually and add it to your project (also next to your \lstinline{main.tex}).
Generate \lstinline{placeholdermacros.tmp} by running \lstinline{placeholderinit.sh} (located in \lstinline{_archive}) with the following command:
\begin{lstlisting}[language=bash]
bash placeholderinit.sh $YourImageFolder
\end{lstlisting}
\subsection{Add a placeholder}
Use \lstinline{\placeholder} to add a image randomly selected from \lstinline{$YourImageFolder}, no argument necessary.
For more control, see next section.
\section{Available commands}
\begin{description}
\item[\lstinline!\placeholderinit{#1}!]
Initialise the randomplaceholder by creating a \linebreak \lstinline!placeholdermacros.tmp! in the project directory. The command is skipped over if the macro file already exist.
\begin{itemize}
\item[\lstinline!#1!] path to the folder with the space holder images. Only images should be present in the folder and names should follow the Unix conventions.
\end{itemize}
\item[\lstinline!\placeholderclean!] Remove \lstinline!placeholdermacros.tmp! so the package can be reinitialised to reflect changes.
\item[\lstinline!\placeholder[#1][#2][#3][#4]!] Insert a randomly selected image. Use a empty argument \lstinline{[]} to use default values.
\begin{itemize}
\item[\lstinline{#1}] Optional, default=htb. Position of the figure, takes floating figure position specifiers.
\item[\lstinline{#2}] Optional, default=\lstinline{\textwidth}. Takes a width specifier.
\item[\lstinline{#3}] Optional, default=None. Text in the figure caption.
\item[\lstinline{#4}] Optional, default=None. Text in the figure label.
\end{itemize}
\item[\lstinline!\includeplaceholder[#1]!] Use this in place of \lstinline!\includegraphics! in the \lstinline{figure} environment.
\begin{itemize}
\item[\lstinline{#1}] Optional, default=\lstinline{width=\textwidth}. Take key-value list for command \lstinline{\includegraphics} from the \lstinline{graphicx} package.
\end{itemize}
\item[\lstinline!\placeholderimage{#1}!] You won't need this noramlly, but here it is: returns the file name of the \lstinline{#1}\textsuperscript{th} image in the image folder.
\end{description}
\section{Examples}
Here are some codes and their results
\begin{lstlisting}
\placeholder
\placeholder[htb][5cm]
\placeholder[][0.3\textwidth][The third argument is the caption]
\placeholder[][0.3\textwidth][][fig5]
Reference figure 5 with \ref{fig5}
% or use a image in your own \begin{figure}
\begin{figure}
\centering
\includeplaceholder[width=5cm]
\caption{Use `includeplaceholder' for more control.}
\end{figure}
\end{lstlisting}
\placeholder%
\placeholder[htb][5cm]
\placeholder[][0.3\textwidth][The third argument is the caption]
\placeholder[][0.5\textwidth][][fig5]
Reference figure 5 with~\ref{fig5}
\begin{figure}
\centering
\includeplaceholder[width=5cm]
\caption{Use `includeplaceholder' for more control.}
\end{figure}
\end{document}