summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/q-and-a/doc/Q-and-A-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/q-and-a/doc/Q-and-A-doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/q-and-a/doc/Q-and-A-doc.tex282
1 files changed, 282 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/q-and-a/doc/Q-and-A-doc.tex b/Master/texmf-dist/doc/latex/q-and-a/doc/Q-and-A-doc.tex
new file mode 100644
index 00000000000..5cdaa152bd3
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/q-and-a/doc/Q-and-A-doc.tex
@@ -0,0 +1,282 @@
+\documentclass[%11pt,
+ use style = classical,
+ % numbered answer,
+ % numbered question,
+ scroll,
+]{Q-and-A}
+
+\def\PackageVersion{2023/11/08}
+\def\PackageSubVersion{}
+
+\newcommand{\QApackage}{{\normalfont\textsf{Q-and-A}}}
+
+
+\title{\QApackage{}\\\smallskip\itshape Typesetting Q\&A-style conversation made easier}
+\author{Jinwen XU}
+% \thanks{Corresponding to: \texttt{\QApackage{}~\PackageVersion\PackageSubVersion}}
+\date{\TheDate{\PackageVersion}[only-year-month], in Paris}
+
+
+\newcommand{\meta}[1]{$\langle${\normalfont\itshape#1}$\rangle$}
+
+
+\begin{document}
+
+\maketitle
+
+"
+ Corresponding to: {\normalfont\texttt{\QApackage{}~\PackageVersion\PackageSubVersion}}.
+
+
+##+ {Introduction}
+
+?
+ What is this?
+
+:
+ \QApackage{} is a \LaTeX{} document class for you to typeset Q\&A-style conversation. It turns a simple pure text Q\&A dialog like this:
+
+ == {code/Q-and-A-doc-code-sample-content.tex}
+
+ into a carefully designed document like this:
+
+ \begin{center}
+ \fbox{\includegraphics[width=.67\textwidth]{code/Q-and-A-doc-code-sample-content-result.pdf}}
+ \end{center}
+
+
+##+ {Preparation}
+
+?
+ That is nice. How can I use it? Is there anything that needs to be prepared?
+
+:
+ You should make sure that this document class is properly installed.
+
+ If you are using TeX Live 2024 or newer, or the most recent version of MikTeX, then this package should already be included, and you don't need to do anything.
+
+ Otherwise, you need to check for package update to see if you can receive it. In case not, you can always go to \href{https://ctan.org/pkg/Q-and-A}{the CTAN page} to download the `.zip` file with all related files included.
+
+
+##+ {Usage}
+
+?
+ Now that I have successfully installed it, could you propose an example of usage?
+
+:
+ Of course. A typical document looks like this:
+
+ == [latex] {code/Q-and-A-doc-code-sample-document.tex}
+
+ The available class options include:
+ \begin{itemize}
+ \item Font size options such as `11pt`, `12pt`.
+ \item `scroll`: turn the scroll mode on, which generates a single-page pdf similar to a long screenshot. It is recommended to use this option if your document contains some large piece of code.
+ \item `use theme = \meta{theme}`: use the selected theme, available choices include: `default` (like the current document), `ChatGPT-light` and `ChatGPT-dark` (see the demo documents).
+ \item `numbered question`, or `question number`: enable the numbering of questions.
+ \item `numbered answer`, or `answer number`: enable the numbering of answers.
+ \item `answer outside the box`, or `answer out of the box` (or even omit `the`): enable another implementation for printing the answer that does not involve putting it into a colored box. This would be useful if the answers contain many long pieces of code while you still want the pages to break normally.
+ \end{itemize}
+
+?
+ What about the main content?
+
+:
+ You have already seen an example of the main content. As you might have noticed, there are several syntaxes. Let me explain.
+
+ [Questions (Q), Answers (A), and Narrations (N)]
+ \begin{itemize}
+ \item A question begins with the prefix `Q:` or `?`.
+ \item An answer begins with the prefix `A:` or `:`.
+ \item A narration begins with the prefix `N:` or `"`.
+ \end{itemize}
+ >>> Note that this depends on the current language. The prefixes `?`, `:` and `"` being universal, yet~—
+ \begin{itemize}
+ \item for French, it is Q\&R\&N, thus the alphabetical prefixes become `Q:`, `R:` and `N:`;
+ \item for German, it is F\&A\&E, thus the alphabetical prefixes become `F:`, `A:` and `E:`;
+ \item for Italian, it is D\&R\&N, thus the alphabetical prefixes become `D:`, `R:` and `N:`;
+ \item for Portuguese and Brazilian, it is P\&R\&N, thus the alphabetical prefixes become `P:`, `R:` and `N:`;
+ \item for Russian, it is B\&O\&P, thus the alphabetical prefixes become `B:`, `O:` and `P:`;
+ \item for Spanish, it is P\&R\&N, thus the alphabetical prefixes become `P:`, `R:` and `N:`;
+ \item for simplified Chinese, it is also possible to use the prefix `问:` for questions, `答:` for answers, and `注:` for narrations; similarly for traditional Chinese;
+ \item for Chinese or Japanese, it is also possible to use the prefix `?` for questions, `:` for answers, and `“`, `”` or `「` for narrations.
+ \end{itemize}
+
+ [Emphasize and Bold]
+ \begin{itemize}
+ \item Use `\textasterisk\meta{text}\textasterisk` to emphasis `\meta{text}`.
+ \item Use `\textasterisk\textasterisk\meta{text}\textasterisk\textasterisk` to make `\meta{text}` into boldface.
+ \item Use `\textasterisk\textasterisk\textasterisk\meta{text}\textasterisk\textasterisk\textasterisk` to combine the previous effects.
+ \end{itemize}
+
+ [Enumerate and Itemize]
+ \begin{itemize}
+ \item **Emphasized version:**
+ \begin{itemize}
+ \item An emphasized `enumerate` is marked by `[\meta{text}]` *at the beginning*, where `\meta{text}` is the text to be emphasized. The numbering is reset at the end of each answer.
+ \QANote{If you wish to restart the numbering from \( 1 \), write an asterisk after the final bracket: `[\meta{text}]\textasterisk`.}
+ \item An emphasized `itemize` is marked by `[\textasterisk\meta{text}]`, where `\meta{text}` is the text to be emphasized.
+ \end{itemize}
+ \item **Normal version:**
+ \begin{itemize}
+ \item When `\meta{text}` is empty, you get the usual appearance of `enumerate` or `itemize`.
+ \end{itemize}
+ \end{itemize}
+ \QANote{With this method of writing, each emphasized `enumerate` and `itemize` must be put into a separate paragraph, and the lists cannot be nested. The usual `enumerate` and `itemize` environments would still be useful if you need nested lists.}
+
+ [Images]
+ Displayed images can be included via one of the following ways:
+ \begin{itemize}
+ \item `\textvert\textvert{} <\meta{width}> \{\meta{image file name}\}` or `\textvert\textvert{} \{\meta{image file name}\} <\meta{width}>`: display in the center.
+ \item `\textleftparen\textleftparen{} <\meta{width}> \{\meta{image file name}\}` or `\textleftparen\textleftparen{} \{\meta{image file name}\} <\meta{width}>`: display on the left.
+ \item `\textrightparen\textrightparen{} <\meta{width}> \{\meta{image file name}\}` or `\textrightparen\textrightparen{} \{\meta{image file name}\} <\meta{width}>`: display on the right.
+ \end{itemize}
+ \QANote{The `\meta{width}` is optional. Here, `\meta{width}` is a number like `0.75`, the unit is `\textbackslash linewidth`. When `\meta{width}` is not given, the width would be full `\textbackslash linewidth`.}
+ \begin{itemize}
+ \item For centered image, the caption can be written via `\textgreater\textgreater{} \meta{caption text}`.
+ \end{itemize}
+ \QANote{Currently, the `\meta{caption text}` shall be directly printed in the center. You may wish to add a pair of parentheses around it.}
+
+ [Code]
+ Due to the current implementation of this document class, it is unfortunate that you cannot directly insert source code in your document. There are some workarounds, though.
+ \begin{itemize}
+ \item For *inline* code, you may simply write it between two backticks `\textbacktick\meta{code}\textbacktick`, similar to the Markdown syntax. However, be aware that special characters need to be escaped, for example, `\textbackslash` should be written as `\textbackslash textbackslash`, `\{` should be written as `\textbackslash\{`, `\%` should be written as `\textbackslash\%`, etc.
+ \item For *displayed* code, stored the code into a separate file, and then use `\textequalsign\textequalsign{} \{\meta{file name}\}` to print~it. You may also use an optional argument like `\textequalsign\textequalsign{} [\meta{language}] \{\meta{file name}\}` to select the language of your code.
+ \QANote{If the answers contain many long pieces of code, you may consider using the class option `answer outside the box`.}
+ \end{itemize}
+
+ [Sections]
+ \begin{itemize}
+ \item You may start a new (*unnumbered*) ---
+ \begin{itemize}
+ \item section, via `\textsharp\textsharp{} \{\meta{section title}\}`;
+ \item subsection, via `\textsharp\textsharp\textsharp{} \{\meta{subsection title}\}`;
+ \item subsubsection, via `\textsharp\textsharp\textsharp\textsharp{} \{\meta{subsubsection title}\}`;
+ \end{itemize}
+ \item If you wish to use the *numbered* version, write `\textsharp\textsharp+`, `\textsharp\textsharp\textsharp+` and `\textsharp\textsharp\textsharp\textsharp+` instead.
+ \end{itemize}
+
+ [Input/Include Files]
+ \begin{itemize}
+ \item Use `\textcolon\textcolon{} \{\meta{file name}\}` to input a file.
+ \item Use `\textcolon\textcolon\textcolon{} \{\meta{file name}\}` to include a file.
+ \end{itemize}
+
+ \medskip
+
+ And don't forget that you are still using \LaTeX, so images, tables and lists can be written as usual.
+
+
+##+ {Cautions}
+
+?
+ I see. Is there anything else for me to be careful about?
+
+:
+ Glad that you asked. Here are several things that should be taken care of:
+ \begin{itemize}
+ \item A question, answer or narration should always begin in a new paragraph.
+ \item An emphasized `enumerate` should also begin in a new paragraph. An emphasized `itemize` should usually begin in a new paragraph, with the exception that it can (partially) be used within an `enumerate`.
+ \item Likewise, a `section`/`subsection`/`subsubsection` should be placed in a separate paragraph.
+ \item Input or inclusion of files should also be operated in a separate paragraph.
+ \item For emphasizing and bolding the text, it would be necessary to separate the asterisks with~`\{\}` in some special cases: `\textasterisk\textasterisk like\textasterisk\textasterisk\{\}\textasterisk\textasterisk\textasterisk this\textasterisk\textasterisk\textasterisk\{\}\textasterisk one\textasterisk`.
+ \item Due to the recognition of the syntax, you cannot directly use characters like `\textasterisk` as usual, especially in math mode. You should consider using an alternative macro, such as `\textbackslash ast` for `\textasterisk` in math mode, or define a command version of the character in the preamble, such as `\textbackslash textasterisk` for `\textasterisk`. A list of predefined commands are:
+ \begin{itemize}
+ \item `\textbackslash textasterisk` for `\textasterisk`;
+ \item `\textbackslash textbacktick` for `\textbacktick`;
+ \item `\textbackslash textcolon` for `\textcolon`;
+ \item `\textbackslash textequalsign` for `\textequalsign`;
+ \item `\textbackslash textleftparen` for `\textleftparen`;
+ \item `\textbackslash textrightparen` for `\textrightparen`;
+ \item `\textbackslash textsharp` for `\textsharp`.
+ \item `\textbackslash textvert` for `\textvert`.
+ \end{itemize}
+ There are also a few that already provided by \LaTeX, such as:
+ \begin{itemize}
+ \item `\textbackslash textbackslash` for `\textbackslash`;
+ \item `\textbackslash textgreater` for `\textgreater`;
+ \item `\textbackslash textless` for `\textless`.
+ \end{itemize}
+ \end{itemize}
+
+
+##+ {Customization}
+
+?
+ Now that we have learned the basic usage, I would like to know more. Can I customize the interface to suit my preferences, for instance?
+
+:
+ Certainly. Apart from using themes via class option, you may also change the identifiers and the labels for each role in the conversation.
+
+ [Changing itentifiers]
+ Instead of the default identifiers, such as `?` for questions, you may also use your preferred one. This can be done via the use of `\textbackslash QASetTypePrefix` in the preamble of your document.
+ \begin{itemize}
+ \item Use `\textbackslash QASetTypePrefix\{Q\}\{\meta{identifiers}\}` to set the identifiers for questions.
+ \item Use `\textbackslash QASetTypePrefix\{A\}\{\meta{identifiers}\}` to set the identifiers for answers.
+ \item Use `\textbackslash QASetTypePrefix\{N\}\{\meta{identifiers}\}` to set the identifiers for narrations.
+ \end{itemize}
+ Here, \meta{identifier} is a comma list of your specified identifiers. For example, the default identifier for narrations is preset via `\textbackslash QASetTypePrefix\{N\}\{N:,",“,”,「\}`.
+ \QANote{Note that, due to its implementation, the identifier cannot contain comma `,` in it. If you wish to use an identifier that contains a comma, you may use `\textbackslash QAAddTypePrefix` instead, which only adds *one* identifier per use.}
+ \QANote{Note also that, the identifiers are *reset* upon changing of language. Thus, you need to put your setting into the corresponding language configuration, for example, via `\textbackslash AddLanguageSetting[\meta{language name}]\{\meta{settings}\}`}
+
+ [Changing labels]
+ You may also change the labels. For example, from the text \textquote{Q:} to a logo icon. This can be done via the use of `\textbackslash SetLogoCode` in the preamble of your document.
+ \begin{itemize}
+ \item Use `\textbackslash SetLogoCode\{Q\}\{\meta{logo code}\}` to set the labels for questions.
+ \item Use `\textbackslash SetLogoCode\{A\}\{\meta{logo code}\}` to set the labels for answers.
+ \end{itemize}
+ Here, \meta{logo code} is the actual code for displaying the corresponding label. For example, the default label for (unnumbered) questions is preset via `\textbackslash SetLogoCode\{Q\}\{\textbackslash textbf\{Q\textbackslash,:\}\}`.
+ \QANote{In the demo document, you can find an example on how to use this command to specify a logo for each role in the conversation.}
+ If you wish to include the question number or answer number, you may use the command `\textbackslash QAShowCounter`:
+ \begin{itemize}
+ \item Use `\textbackslash QAShowCounter\{Q\}` to step the counter of question and print it.
+ \item Use `\textbackslash QAShowCounter\{A\}` to step the counter of answer and print it.
+ \end{itemize}
+ For example, the default label for numbered questions is preset by adding `\textbackslash QAShowCounter\{Q\}` to the unnumbered version: `\textbackslash SetLogoCode\{Q\}\{\textbackslash textbf\{Q\textbackslash QAShowCounter\{Q\}\textbackslash,:\}\}`.
+
+
+##+ {Known Issues}
+
+?
+ Is there any known issue with this document class?
+
+:
+ Unfortunately, yes `:(`.
+
+ Below is a list of known issues:
+
+ \begin{itemize}
+ \item Currently, the code highlight is done by the package `listings`. Due to its own limitations, the result is still far from satisfactory. Using `minted` instead could improve the situation, but this would require `-shell-escape` and some external tweaking, thus it would still take some effort to make it work with the current document class.
+ \item Due to the current implementation, one cannot direct write code (either inline or displayed) within the text (alternative solution has been proposed above).
+ \item Due to the current implementation, one may not be able to directly write certain characters (such as `\textasterisk`) in the text, this might be especially inconvenient in math mode (temporary alternative solution has been proposed above).
+ \item Due to the current implementation, the method for inputting and including subfiles doesn't really work like `\textbackslash input` and `\textbackslash include`. In particular, the current type of conversation would be reset, this might cause some confusion in certain cases.
+ % \item The code block containing long piece of code usually won't properly break across the page (which is essentially why this documentation and the demo documents enabled the `scroll` mode).
+ %% 2023-11-05, solved with the new option "answer outside the box".
+ \item Due to the current implementation, though it is already possible to automatically adopt the identifiers and labels for supported languages, you still need to use the identifiers `Q`, `A` and `N` when setting them.
+ \item Currently, for typesetting questions and answers, the text is in fact being put into some sort of `description` list (upon reflection, why did I do this? I could have simply put the label into margin...). As a result, the level of lists might be slightly messed up, which could sometimes lead to issues with the list labels.
+ \end{itemize}
+
+
+##+ {Get Support}
+
+?
+ What should I do if I encounter any problem?
+
+:
+ If you run into any issues or have ideas for improvement, feel free to discuss on:
+ \begin{center}
+ \url{https://github.com/Jinwen-XU/Q-and-A/issues}
+ \end{center}
+ or email me via \href{mailto:ProjLib@outlook.com}{\texttt{ProjLib@outlook.com}}.
+
+
+\vspace{3\baselineskip}
+
+% ---
+
+% "
+% Below is the code of the current document.
+
+% == [latex] {\jobname.tex}
+
+\end{document}