User Guide

Welcome to the ADP-GITHUB User Guide! I will try to do my best explaining how to use ADP-GITHUB. If this is not sufficient, note that every piece of documentation of ADP-GITHUB has been generated by itself. So you can see the source code and see how ADP-GITHUB has been used. For example, this file was generated using the source located at scribble/user-guide.scrbl .

• Titles
• Table of contents
• Tables
• Lists
• Text style
• Hyperlinks
• Quoted text
• Images
• Code blocks
• Descriptions and cross references
  • Descriptions
  • References
• Glossaries
• Table of symbols

Titles

You can add titles in your documentation. So you can organize your guide with different sections (like I do in this guide). The macros that add titles are adpgh:title*, adpgh:title, adpgh:subtitle and adpgh:subsubtitle. They need a string as the first argument. For example, if I write this:

@title[:toc nil]{This is a title}
@subtitle[:toc nil :tag tag-used-below]{This is a subtitle}
@subsubtitle[:toc nil]{This is a subsubtitle}

You will see this:

This is a title

This is a subtitle

This is a subsubtitle

Note that they can receive a keyword argument :toc. If nil is used, these titles won't appear in any table of content.

Also, if we want additional levels for the title we should use adpgh:title*. Works the same way as others but accepts an additional keyword argument :level.

Table of contents

We can create a table of contents with the function adpgh:table-of-contents. It will look for all titles used in the current file and make an hyperlink to these titles.

@table-of-contents[]

• Titles
• Table of contents
• Tables
• Lists
• Text style
• Hyperlinks
• Quoted text
• Images
• Code blocks
• Descriptions and cross references
  • Descriptions
  • References
• Glossaries
• Table of symbols

Additionally, we can specify the levels of titles that should appear. For example, we can specify only subsubtitles (titles of level 2):

@table-of-contents[:min-level 2 :max-level 2]

• Descriptions
• References

We can also include or exclude specific titles using tags. If you look back the previous section we created a subtitle with the tag tag-used-below. Let's use it:

@table-of-contents[:min-level 2 :max-level 2 :include (tag-used-below)]

• This is a subtitle
  • Descriptions
  • References

Tables

You can add tables using the macros adpgh:table, adpgh:row and adpgh:cell. The best way to see how to use it is an example. Imagine we have some info in our lisp files:

(defparameter peter-info '(34 "Peter Garcia" 1435))
(defparameter maria-info '(27 "Maria Martinez" 1765))
(defparameter laura-info '(53 "Laura Beneyto" 1543))

(defun get-age (info)
  (first info))

(defun get-name (info)
  (second info))

(defun get-salary (info)
  (third info))

;; Returns
GET-SALARY

Now we can create a table like this:

@table[
  @row[
    @cell{Age} @cell{Name} @cell{Salary}
  ]
  @row[
    @cell[(get-age peter-info)] @cell[(get-name peter-info)] @cell[(get-salary peter-info)]{€}
  ]
  @row[
    @cell[(get-age maria-info)] @cell[(get-name maria-info)] @cell[(get-salary maria-info)]{€}
  ]
  @row[
    @cell[(get-age laura-info)] @cell[(get-name laura-info)] @cell[(get-salary laura-info)]{€}
  ]
]

And you will see this:

Age	Name	Salary
34	Peter Garcia	1435€
27	Maria Martinez	1765€
53	Laura Beneyto	1543€

Lists

You can add lists with adpgh:itemize or adpgh:enumerate. For example:

@itemize[
  @item{Vegetables:}
  @enumerate[
    @item{3 peppers}
    @itemize[
      @item{1 green pepper}
      @item{@(- 3 1) red pepper}
    ]
    @item{0.25 Kg of carrots}
  ]
  @item{Fruits:}
  @enumerate[
    @item{0.5 Kg of apples}
    @item{6 oranges}
  ]
]

You will see this:

• Vegetables:
  1. 3 peppers
     • 1 green pepper
     • 2 red pepper
  2. 0.25 Kg of carrots
• Fruits:
  1. 0.5 Kg of apples
  2. 6 oranges

Text style

We can enrich the text with the macros adpgh:bold, adpgh:italic, adpgh:emphasis and adpgh:code. For example:

As @bold{Andrew} said: @italic{You only need @(+ 1 2 3)} @code{coins} @italic{to enter in} @emphasis{The Giant Red Tree}.

You will see this:

As Andrew said: You only need 6 coins to enter in The Giant Red Tree.

You can nest adpgh:bold and adpgh:italic functions:

The large @bold{house with @italic{the old woman}}.

The large house with the old woman.

Hyperlinks

Adding hyperlinks can be done with adpgh:link. It needs an web address and the text of the hyperlink.

A link to the @link[:address "https://www.lispworks.com/documentation/HyperSpec/Front/index.htm"]{hyperspec}.

You will see:

A link to the hyperspec.

Quoted text

You can quote text:

@quoted{
A driller by day
A driller by night
Bugs never hurt
As they're frozen from fright

My c4 goes boom
Sharp as a ruler
Just me and my baby
@italic{Perfectly Tuned Cooler}

- A Deep Rock Galactic poem by @link[:address "https://www.reddit.com/user/TEAdown/"]{TEAdown}
}

A driller by day
A driller by night
Bugs never hurt
As they're frozen from fright

My c4 goes boom
Sharp as a ruler
Just me and my baby
Perfectly Tuned Cooler

- A Deep Rock Galactic poem by TEAdown

Images

You can add images with the macro adpgh:image. For example, an image is located at guides/images/. If I evaluate the next expression:

@image["/images/Lisp_logo.svg" :alt-text "Lisp logo" :scale 0.1]

You will see:

The path is always treated as a relative pathname to the system's root directory.

Code blocks

A good Lisp tutorial must include Lisp code examples. ADP defines some macros to print code blocks: adpgh:code-block and adpgh:example. The first macro does not evaluate the code. So, for example if you write this:

@code-block{
  (this is not (valid code))
  (but it (is (ok)))
}

You will see:

(this is not (valid code))
(but it (is (ok)))

The macro adpgh:code-block allows you to write non-Lisp code as well. It can receive, optionally, the language to be used:

@code-block[:lang "c"]{
  int main(){
    printf("Hello world!");
    return 0;
  }
}

int main(){
  printf("Hello world!");
  return 0;
}

If you want to print also @-syntax expressions, you can use the |{...}| form:

@code-block[:lang "scribble"]|{
  @cmd[datum]{parse-body}
}|

@cmd[datum]{parse-body}

Lastly, adpgh:example evaluates the Lisp code you write on it. And what is more, it prints the standard output as well as the returned values. For example, writing this:

@example{
  (loop for i from 0 below 10
        do (print i))
  (values "Hello" "world")
}

You will see:

(loop for i from 0 below 10
      do (print i))
(values "Hello" "world")

;; Output

0 
1 
2 
3 
4 
5 
6 
7 
8 
9 

;; Returns
"Hello"
"world"

See that we used the {} form. I. e., we are writing text. It will be read and then evaluated. We can also use the |{}| form to make scribble code to be printed:

@example|{
  (print @+[3 4])
}|

(print @+[3 4])

;; Output

7 

;; Returns
7

Descriptions and cross references

If we need to document our code, we may want to generate a refernce page where all the functions, variables or classes are described properly. Also, a good system to make a link to a description would be really nice.

ADP-GITHUB creates references from descriptions and titles. Each time you create a description or a title, a reference can be created to refer to that description or title.

There are five types of descriptions: functions, variables, classes, packages and systems. And each type of description can be referenced by a reference of the same type.

Descriptions

Descriptions can be inserted with the functions adpgh:function-description, adpgh:variable-description, adpgh:class-description, adpgh:package-description and adpgh:system-description.

For example, ADP-GITHUB defines the function adpgh:image we've seen before. I we want a description of that function we need to write the following:

@function-description[image]

And we see this:

Function: adpgh:image (&rest args-sym)

Inserts an image.

It must receive the path to the image (relative to the project's root directory).
Optionally, it can receive an alternative text description and the scale size of the image.

The same goes for the rest of functions. For example, we can see the description of the system adp-github.

@system-description["adp-github"]

System: adp-github

ADP extension to generate github markdown files.

• Author: Héctor Galbis Sanchis
• License: MIT
• Depends on: alexandria, closer-mop, adp, trivial-arguments, hyperspec, cl-ppcre

Or its package:

@package-description[#:adpgh]

Package: ADP-GITHUB

The main package of adp-github.

• Nicknames: ADPGH
• Exported symbols: bold, cell, class-description, class-glossary, clref, code, code-block, cref, emphasis, enumerate, example, fref, function-description, function-glossary, image, italic, item, itemize, link, output-file, package-description, pref, quoted, row, sref, subsubtitle, subtitle, system-description, table, table-of-classes, table-of-contents, table-of-functions, table-of-variables, text, title, title*, tref, variable-description, variable-glossary, vref

For variables, let's get the internal symbol adpgh::*tags*.

@variable-description[adpgh::*tags*]

Variable: adpgh::*tags*

The tags container.

Classes too. Let's define the following classes:

(defclass base-class () ())

(defclass complete-class (base-class)
  ((internal-slot :documentation "Some slot for internal use.")
   (title :reader complete-class-title
          :accessor complete-title
          :allocation :class))
  (:documentation
   "An example of a class with a lot of things."))

;; Returns
#<STANDARD-CLASS ADPGH-DOCS::COMPLETE-CLASS>

Let's see its description:

@class-description[complete-class]

Class: adpgh-docs::complete-class

An example of a class with a lot of things.

• Direct slots:

  • adpgh-docs::internal-slot
    • Some slot for internal use.
    • Allocation: :instance
  • adpgh:title
    • Allocation: :class
    • Readers: adpgh-docs::complete-title, adpgh-docs::complete-class-title
    • Writers: (setf adpgh-docs::complete-title)

• Metaclass: standard-class

• Precedence list: adpgh-docs::complete-class, adpgh-docs::base-class, standard-object, sb-pcl::slot-object, t

• Direct superclasses: adpgh-docs::base-class

References

We can differentiate between title references and description references. As you can guess, title references will reference to a title of any level. On the other hand, descriptions references will reference to a description.

The functions that inserts references are adpgh:tref, adpgh:fref, adpgh:vref, adpgh:cref, adpgh:pref and adpgh:sref. They insert a reference to a title, function, variable, class, package and system respectively.

The adpgh:tref function is a bit different from the others. It accepts a variable number of arguments, and it should receive a keyword argument :tag.

@tref[user-guide]{A link to the top.}

A link to the top.

As you can see, the rest of elements received are used to indicate the text of the inserted link. The rest of reference functions also accept these elements to form the text to be shown. But, instead of receiving a :tag keyword they receive a symbol or a descriptor.

Above we've inserted a system description. We can now create a reference to that description:

@sref["adp-github"]

And we will see:

adp-github

Or, optionally, with text:

@sref["adp-github"]{The system of adp-github.}

And we will see:

The system of adp-github.

The same goes to the rest of types. However, there is one more thing we should know. If I use the following:

@fref[image]

adpgh:image

you will see that the link goes to the reference page and not to the description we wrote above. That's because glossaries (that we will explain in the following section) have precedence over single descriptions.

Another useful function is adpgh:clref. With it, we can make reference to a Common Lisp Hyperspec symbol.

@clref[prin1]

prin1

Glossaries

A system may export a ton of symbols, maybe hundreds. For that reason we need some way to insert descriptions automatically. That is the job of glossaries. We have glossaries of three types: functions, variables and classes. They can be inserted with the functions adpgh:function-glossary, adpgh:variable-glossary and adpgh:class-glossary.

Each type of glossary will iterate over all the exported symbols looking for possible descriptions to insert. For example. the adpgh:variable-glossary will look for exported symbols that has a value associated with it.

The best example I can show here is the reference page of this project.

Table of symbols

Similarly to table of contents, we can create a bunch of hyperlink to function, variable or class descriptions. These sets of hyperlinks are table of symbols. We can create them with adpgh:table-of-functions, adpgh:table-of-variables and adpgh:table-of-classes.

These table of symbols will only generate hyperlinks for the descriptions appearing in the current file.

For example, these are the function descriptions printed in this file:

@table-of-functions[]

• adpgh:image