Build Scripts

The md-to-pdf.sh script is the heart of the ASIR-ISO build system. It orchestrates the conversion of Markdown source files into professionally formatted PDF documents for all 12 didactic units.

Script Location

The build script is located at:

bin/md-to-pdf.sh

Basic Usage

cd bin
./md-to-pdf.sh 01    # Build UD01
./md-to-pdf.sh 05    # Build UD05
./md-to-pdf.sh 12    # Build UD12

The script must be run from the bin/ directory or with the correct relative paths to source files and templates.

Script Architecture

The script is organized into several key sections:

1. Environment Setup

The script begins by preparing the output directory:

echo "Preparando el entorno"
mkdir -p PDFS

2. Configuration Variables

Defines templates, paths, and pandoc options:

TEMPLATE_TEX="../rsrc/templates/temas-tpl.latex"
TEMPLATE_TEX_TAREAS="../rsrc/templates/tareas-tpl.latex"
TEMPLATE_TEX_ANEXOS="../rsrc/templates/anexos-tpl.latex"

3. Didactic Unit Definitions

Maps unit numbers to directory names:

UD01_NAME="UD01_IntroduccionSistemasOperativos"
UD02_NAME="UD02_Virtualizacion"
UD03_NAME="UD03_Instalacion_Arranque"
# ... through UD12

4. Helper Functions

Provides utilities for output formatting and file processing:

say_ok(): Display success messages in green
say_error(): Display error messages in red
say_file(): Check file existence and report status
make_teoria(): Generate theory PDFs
make_practicas(): Generate task PDFs
make_anexos(): Generate annex PDFs
move_pdfs(): Organize output files

5. Main Processing Logic

A case statement handles the user’s selection:

case $1 in 
    "01") make_UD01 ;;
    "02") make_UD02 ;;
    # ...
    "all") make_UD01; make_UD02; ... ;;
esac

Core Functions

make_teoria()

Combines all theory files into a single PDF:

Navigate to Unit Directory

cd ${UD01_NAME}

Run Pandoc

Process all Teoria_*.md files:

pandoc --template ${TEMPLATE_TEX} \
  ${PANDOC_OPTIONS} \
  -o ${PDF_PATH}/${UDTEORIA}_Teoria.pdf \
  Teoria_*.md

Report Status

say_ok "$(readlink -f ${PDF_PATH}/${UDTEORIA}_Teoria.pdf)"

make_practicas()

Generates individual PDFs for each task:

Iterate Through Task Files

for ejer in $(ls -1 Tarea_*.md); do

Extract Number and Name

Parse the filename to get metadata:

NUM=$(echo $ejer | cut -d "_" -f2 | cut -d "." -f1)
NOMBRE=$(echo $ejer | cut -d "_" -f3 | cut -d "." -f1)

Generate PDF

pandoc --template ${TEMPLATE_TEX_TAREAS} \
  ${PANDOC_OPTIONS} \
  -o ${PDF_PATH}/${UDPRACTICAS}_Tarea_${NUMP}_${NOMBRE}.pdf \
  $ejer

Increment Counter

let NUMP=NUMP+1

The task numbering in output filenames is sequential based on alphabetical order of source files, not the number in the filename.

make_anexos()

Works similarly to make_practicas() but processes Anexo_*.md files using the annexes template.

move_pdfs()

Organizes generated PDFs into unit-specific folders:

mkdir -p PDFS/${UDNAME}
mv PDFS/*.pdf PDFS/${UDNAME}/
say_ok "PDFS generados en : PDFS/${UDNAME}/"

Pandoc Configuration

The script uses consistent pandoc options across all conversions:

Pandoc Options Explained

Font Size

-V fontsize=12pt

Sets the base font size to 12 points for comfortable reading.Main Font

-V mainfont="Ubuntu"

Uses the Ubuntu font family for all text.PDF Engine

--pdf-engine=xelatex

Uses XeTeX for Unicode support and modern typography.Template

--template ${TEMPLATE_TEX}

Applies custom LaTeX template for consistent styling.

Installation Guides

Some units include installation guides that are processed alongside regular materials:

make_guia_ubuntu_bionic(){
    echo " * [ GUIA ] : Ubuntu Bionic"
    cd ${GUIAS_PATH}
    pandoc --template ${TEMPLATE_TEX} \
      ${PANDOC_OPTIONS} \
      -o ${PDF_PATH}/${GUIA_BIONIC}.pdf \
      ${GUIA_BIONIC}.md
    cd ..
}

Guides are called from unit-specific functions:

make_UD02(){
    cd ${UD02_NAME}
    make_teoria ${UD02_NAME}
    make_practicas ${UD02_NAME}
    cd ..
    
    # Installation guides for this unit
    make_guia_ubuntu_bionic
    make_guia_xubuntu_bionic
    
    move_pdfs ${UD02_NAME}
}

Output Structure

After running the script, PDFs are organized as follows:

PDFS/
├── UD01_IntroduccionSistemasOperativos/
│   ├── UD01_Teoria.pdf
│   ├── UD01_Tarea_1_TiposDeAplicaciones.pdf
│   ├── UD01_Tarea_2_SistemasOperativos.pdf
│   └── UD01_Tarea_3_Licencias.pdf
├── UD02_Virtualizacion/
│   ├── UD02_Teoria.pdf
│   ├── UD02_Tarea_1_DiscosDurosVirtuales.pdf
│   ├── Guia_Ubuntu_Bionic.pdf
│   └── Guia_Xubuntu_Bionic.pdf
└── ...

Status Indicators

The script uses color-coded output to show progress:

 * [ OK ] : /home/user/ASIR-ISO/bin/PDFS/UD01_Teoria.pdf

Color codes:

RED='\033[0;31m'
GREEN="\033[0;32m"
NC='\033[0m' (No Color)

Customization

Changing Font Size

Modify the PANDOC_OPTIONS variable:

PANDOC_OPTIONS="-V fontsize=14pt -V mainfont=\"Ubuntu\" --pdf-engine=xelatex"

Using Different Fonts

Change the mainfont variable:

PANDOC_OPTIONS="-V fontsize=12pt -V mainfont=\"Liberation Sans\" --pdf-engine=xelatex"

Ensure the font is installed on your system. Check with fc-list | grep "FontName"

Adding New Units

To add a 13th didactic unit:

Define the Unit Name

UD13_NAME="UD13_NewTopicName"

Create Processing Function

make_UD13(){
    cd ${UD13_NAME}
    make_teoria ${UD13_NAME}
    make_practicas ${UD13_NAME}
    cd ..
    move_pdfs ${UD13_NAME}
}

Add to Case Statement

case $1 in
    # ... existing cases
    "13")
        make_UD13
        ;;
    "all")
        make_UD01
        # ... existing units
        make_UD13
        ;;
esac

Error Handling

The script includes basic error handling:

if [ -f $1 ]; then 
    say_ok "$(readlink -f $1)"
else
    say_error " [ Warning ] : Not a file $1 "
fi

Exit codes:

exit 0: Successful completion
exit 1: Unknown unit specified

Performance

Processing times vary by unit:

Single unit: 10-30 seconds
All units: 3-5 minutes
With guides: Additional 10-15 seconds per guide

Performance depends on the number of files, document length, and system resources.

Troubleshooting

Script Won’t Run

Problem: Permission denied Solution: Make the script executable:

chmod +x bin/md-to-pdf.sh

PDFs Not Generated

Problem: No output files Solution: Check that:

You’re running from the correct directory
Source .md files exist in unit folders
Dependencies are installed (see Dependencies)

Template Not Found

Problem: --template error from pandoc Solution: Verify template paths:

ls -la ../rsrc/templates/

Wrong Output Location

Problem: PDFs appear in unexpected location Solution: The script uses readlink -f to resolve absolute paths. Ensure you run it from bin/ directory.

Next Steps

Now that you understand the build scripts:

Review the Style Guide - Learn formatting conventions
Check the Build Overview - Understand the complete workflow
Try building a unit - Generate your first PDFs

Introduction

Build System

Script Location

Basic Usage

Script Architecture

1. Environment Setup

2. Configuration Variables

3. Didactic Unit Definitions

4. Helper Functions

5. Main Processing Logic

Core Functions

make_teoria()

make_practicas()

make_anexos()

move_pdfs()

Pandoc Configuration

Installation Guides

Output Structure

Status Indicators

Customization

Changing Font Size

Using Different Fonts

Adding New Units

Error Handling

Performance

Troubleshooting

Script Won’t Run

PDFs Not Generated

Template Not Found

Wrong Output Location

Next Steps

Build docs developers (and LLMs) love

Introduction

Build System

​Script Location

​Basic Usage

​Script Architecture

​1. Environment Setup

​2. Configuration Variables

​3. Didactic Unit Definitions

​4. Helper Functions

​5. Main Processing Logic

​Core Functions

​make_teoria()

​make_practicas()

​make_anexos()

​move_pdfs()

​Pandoc Configuration

​Installation Guides

​Output Structure

​Status Indicators

​Customization

​Changing Font Size

​Using Different Fonts

​Adding New Units

​Error Handling

​Performance

​Troubleshooting

​Script Won’t Run

​PDFs Not Generated

​Template Not Found

​Wrong Output Location

​Next Steps

Build docs developers (and LLMs) love

Script Location

Basic Usage

Script Architecture

1. Environment Setup

2. Configuration Variables

3. Didactic Unit Definitions

4. Helper Functions

5. Main Processing Logic

Core Functions

make_teoria()

make_practicas()

make_anexos()

move_pdfs()

Pandoc Configuration

Installation Guides

Output Structure

Status Indicators

Customization

Changing Font Size

Using Different Fonts

Adding New Units

Error Handling

Performance

Troubleshooting

Script Won’t Run

PDFs Not Generated

Template Not Found

Wrong Output Location

Next Steps