Guide utilisateur¶

Ce guide complet vous accompagne dans l'utilisation d'artmeta, de la création de votre premier fichier de métadonnées à la génération de LaTeX pour différentes revues.

Table des matières¶

Démarrage rapide
Format du fichier YAML
Commandes disponibles
Workflows typiques
Cas d'usage avancés

Démarrage rapide¶

1. Créer un fichier de métadonnées¶

artmeta init

Cette commande génère un fichier art.yml contenant un template :

title: "Titre de l'article"

authors:
  - firstname: "Prénom"
    lastname: "Nom"
    email: "prenom.nom@institution.fr"
    orcid: "0000-0000-0000-0000"
    affiliations: [1]
    corresponding: true

affiliations:
  - id: 1
    name: "Nom du laboratoire"
    institution: "Université X"
    city: "Ville"
    country: "France"

abstract: |
  Résumé de l'article...

keywords:
  - "mot-clé 1"
  - "mot-clé 2"

msc_codes:
  - "35K15"

Options utiles :

# Spécifier un nom de fichier
artmeta init -o my_article.yml

# Forcer l'écrasement si le fichier existe
artmeta init -f

2. Éditer vos métadonnées¶

Ouvrez art.yml dans votre éditeur préféré et remplissez les informations de votre article.

3. Valider¶

Avant de générer du LaTeX, validez votre fichier :

artmeta validate

La validation vérifie : - ✅ Présence des champs obligatoires (title, authors, abstract) - ✅ Format des ORCID (0000-0000-0000-0000) - ✅ Format des emails - ✅ Codes MSC valides (Mathematical Subject Classification) - ✅ Cohérence des affiliations (tous les IDs référencés existent)

Exemple de sortie :

✓ Validation réussie
  - 3 auteur(s)
  - 2 affiliation(s)
  - 5 mots-clés
  - 2 codes MSC

4. Générer le code LaTeX¶

artmeta generate --journal amsart

Affiche le code LaTeX pour la classe amsart :

\title{Titre de l'article}

\author{Prénom Nom}
\address{Nom du laboratoire, Université X, Ville, France}
\email{prenom.nom@institution.fr}
% ORCID: 0000-0000-0000-0000

\begin{abstract}
Résumé de l'article...
\end{abstract}

\keywords{mot-clé 1, mot-clé 2}
\subjclass[2020]{35K15}

\maketitle

5. Insérer dans votre fichier .tex¶

artmeta generate --journal amsart --insert main.tex

Le code est inséré entre balises automatiques dans main.tex :

\documentclass{amsart}

% BEGIN AUTO-GENERATED [amsart]
\title{Titre de l'article}
\author{...}
...
% END AUTO-GENERATED [amsart]

\begin{document}

Votre contenu...

\end{document}

Format du fichier YAML¶

Champs disponibles¶

Champs obligatoires¶

Champ	Type	Description
`title`	string	Titre de l'article
`authors`	list	Liste des auteurs (minimum 1)
`abstract`	string	Résumé de l'article

Champs optionnels¶

Champ	Type	Description
`title_short`	string	Titre court (pour en-têtes)
`affiliations`	list	Liste des affiliations
`keywords`	list	Mots-clés
`msc_codes`	list	Codes MSC 2020
`acknowledgments`	string	Remerciements
`date`	string	Date de soumission

Structure d'un auteur¶

authors:
  - firstname: "John"           # Obligatoire
    lastname: "Doe"             # Obligatoire
    email: "john.doe@univ.fr"   # Recommandé
    orcid: "0000-0001-2345-6789" # Optionnel
    affiliations: [1, 2]        # IDs des affiliations
    corresponding: true         # Auteur correspondant

Champs auteur :

Champ	Obligatoire	Format
`firstname`	✅ Oui	Chaîne
`lastname`	✅ Oui	Chaîne
`email`	⚠️ Recommandé	`user@domain.ext`
`orcid`	❌ Non	`0000-0000-0000-0000`
`affiliations`	❌ Non	Liste d'IDs
`corresponding`	❌ Non	`true` ou `false`

Structure d'une affiliation¶

affiliations:
  - id: 1                                    # Obligatoire, unique
    name: "Laboratoire de Mathématiques"    # Obligatoire
    institution: "Université Paris-Saclay"  # Obligatoire
    city: "Orsay"                           # Optionnel
    country: "France"                       # Optionnel
    department: "Département de Maths"      # Optionnel

Champs affiliation :

Champ	Obligatoire	Description
`id`	✅ Oui	Identifiant unique (integer)
`name`	✅ Oui	Nom du laboratoire/groupe
`institution`	✅ Oui	Nom de l'institution
`city`	❌ Non	Ville
`country`	❌ Non	Pays
`department`	❌ Non	Département

Exemple complet¶

title: "On the convergence of stochastic gradient descent"
title_short: "Convergence of SGD"

authors:
  - firstname: "Alice"
    lastname: "Martin"
    email: "alice.martin@univ-paris.fr"
    orcid: "0000-0001-2345-6789"
    affiliations: [1]
    corresponding: true

  - firstname: "Bob"
    lastname: "Dupont"
    email: "bob.dupont@eth.ch"
    orcid: "0000-0002-3456-7890"
    affiliations: [2, 3]

affiliations:
  - id: 1
    name: "Laboratoire de Probabilités et Modèles Aléatoires"
    institution: "Sorbonne Université"
    city: "Paris"
    country: "France"

  - id: 2
    name: "Institute for Mathematical Research"
    institution: "ETH Zürich"
    city: "Zürich"
    country: "Switzerland"

  - id: 3
    name: "Swiss Data Science Center"
    institution: "ETH Zürich"
    city: "Zürich"
    country: "Switzerland"

abstract: |
  We study the convergence properties of stochastic gradient descent
  for non-convex optimization. We prove that under mild assumptions,
  the algorithm converges to a local minimum with probability one.

keywords:
  - "stochastic optimization"
  - "gradient descent"
  - "non-convex optimization"
  - "convergence analysis"

msc_codes:
  - "90C26"  # Nonconvex programming
  - "65K05"  # Numerical optimization
  - "68Q25"  # Analysis of algorithms

acknowledgments: |
  This work was supported by ANR grant ANR-XX-XXXX-01.

date: "2024-10-18"

Commandes disponibles¶

`artmeta init`¶

Crée un fichier template de métadonnées.

Usage :

artmeta init [OPTIONS]

Options : - -o, --output FILE : Nom du fichier de sortie (défaut: art.yml) - -f, --force : Écraser le fichier s'il existe déjà

Exemples :

# Créer art.yml
artmeta init

# Créer avec un nom personnalisé
artmeta init -o paper_neurips.yml

# Forcer l'écrasement
artmeta init -f

`artmeta validate`¶

Valide un fichier de métadonnées.

Usage :

artmeta validate [OPTIONS]

Options : - -m, --metadata FILE : Fichier à valider (défaut: art.yml)

Exemples :

# Valider art.yml
artmeta validate

# Valider un fichier spécifique
artmeta validate -m my_article.yml

Codes de sortie : - 0 : Validation réussie - 1 : Erreurs de validation

`artmeta info`¶

Affiche un résumé des métadonnées.

Usage :

artmeta info [OPTIONS]

Options : - -m, --metadata FILE : Fichier source (défaut: art.yml)

Exemple de sortie :

Titre: On the convergence of stochastic gradient descent
Titre court: Convergence of SGD

Auteurs (2):
  1. Alice Martin (alice.martin@univ-paris.fr) [Correspondant]
     Affiliations: Laboratoire de Probabilités et Modèles Aléatoires
     ORCID: 0000-0001-2345-6789

  2. Bob Dupont (bob.dupont@eth.ch)
     Affiliations: Institute for Mathematical Research, Swiss Data Science Center
     ORCID: 0000-0002-3456-7890

Mots-clés: stochastic optimization, gradient descent, non-convex optimization, convergence analysis
Codes MSC: 90C26, 65K05, 68Q25

`artmeta stats`¶

Affiche des statistiques sur le contenu.

Usage :

artmeta stats [OPTIONS]

Options : - -m, --metadata FILE : Fichier source (défaut: art.yml)

Exemple de sortie :

Statistiques:
  - Auteurs: 2
  - Affiliations: 3
  - Mots-clés: 4
  - Codes MSC: 3
  - Mots dans l'abstract: 34
  - Caractères dans l'abstract: 245

`artmeta generate`¶

Génère le code LaTeX pour une classe de revue.

Usage :

artmeta generate --journal CLASS [OPTIONS]
artmeta generate --autodetect-from FILE.tex [OPTIONS]

Classes supportées : - amsart - American Mathematical Society - elsarticle - Elsevier journals - svjour3 - Springer journals - siamart - SIAM journals - article - LaTeX standard

Options : - -j, --journal CLASS : Classe de document à générer - --autodetect-from FILE.tex : Détecter automatiquement la classe depuis un fichier .tex existant - -m, --metadata FILE : Fichier source (défaut: art.yml) - -o, --output FILE : Sauvegarder dans un fichier - -i, --insert FILE : Insérer dans un fichier .tex existant

Exemples :

# Afficher le code pour amsart
artmeta generate --journal amsart
# ou en version courte
artmeta generate -j amsart

# Autodétection de la classe depuis un fichier .tex
artmeta generate --autodetect-from main.tex

# Sauvegarder dans un fichier
artmeta generate -j amsart -o metadata_ams.tex

# Insérer directement dans main.tex
artmeta generate -j amsart --insert main.tex

# Utiliser un fichier de métadonnées personnalisé
artmeta generate -j elsarticle -m paper.yml --insert submission.tex

# Autodétection et insertion
artmeta generate --autodetect-from main.tex --insert main.tex

`artmeta switch`¶

Change la classe de revue dans un fichier .tex existant.

Usage :

artmeta switch --journal CLASS TEXFILE [OPTIONS]

Options : - -j, --journal CLASS : Nouvelle classe de document (obligatoire) - -m, --metadata FILE : Fichier source (défaut: art.yml)

Exemples :

# Changer de amsart vers elsarticle
artmeta switch --journal elsarticle main.tex
# ou en version courte
artmeta switch -j elsarticle main.tex

# Avec métadonnées personnalisées
artmeta switch -j svjour3 paper.tex -m metadata.yml

Comportement : 1. Recherche le bloc % BEGIN AUTO-GENERATED [...] dans le fichier 2. Remplace le contenu par la nouvelle classe 3. Met à jour la balise avec le nouveau nom de classe

`artmeta hal-xml`¶

Génère un fichier XML compatible HAL.

Usage :

artmeta hal-xml [OPTIONS]

Options : - -m, --metadata FILE : Fichier source (défaut: art.yml) - -o, --output FILE : Fichier de sortie (défaut: stdout)

Exemples :

# Afficher le XML
artmeta hal-xml

# Sauvegarder dans un fichier
artmeta hal-xml -o hal_metadata.xml

# Avec métadonnées personnalisées
artmeta hal-xml -m paper.yml -o hal_paper.xml

Workflows typiques¶

Workflow 1 : Soumission à une revue AMS¶

# 1. Créer les métadonnées
artmeta init -o paper_ams.yml

# 2. Éditer paper_ams.yml dans votre éditeur

# 3. Valider
artmeta validate -m paper_ams.yml

# 4. Créer votre fichier LaTeX principal
cat > main.tex << 'EOF'
\documentclass{amsart}

% Les métadonnées seront insérées ici

\begin{document}

\section{Introduction}
...

\end{document}
EOF

# 5. Insérer les métadonnées
artmeta generate -j amsart -m paper_ams.yml --insert main.tex

# 6. Compiler
pdflatex main.tex

Workflow 2 : Changer de revue¶

Vous avez soumis à une revue AMS, mais vous devez maintenant soumettre à Elsevier :

# Simplement changer la classe
artmeta switch -j elsarticle main.tex

# Mettre à jour la classe de document si nécessaire
sed -i 's/\\documentclass{amsart}/\\documentclass{elsarticle}/' main.tex

# Recompiler
pdflatex main.tex

Workflow 3 : Soumission HAL¶

# 1. Générer le LaTeX pour votre article
artmeta generate -j amsart --insert paper.tex

# 2. Générer les métadonnées HAL
artmeta hal-xml -o hal_metadata.xml

# 3. Compiler le PDF
pdflatex paper.tex

# 4. Soumettre sur HAL avec paper.pdf et hal_metadata.xml

Workflow 4 : Plusieurs versions simultanées¶

Maintenir plusieurs versions de votre article pour différentes revues :

# Structure des fichiers
# art.yml           <- Métadonnées centrales
# ams_version/main.tex
# elsevier_version/main.tex
# springer_version/main.tex

# Générer pour AMS
artmeta generate -j amsart --insert ams_version/main.tex

# Générer pour Elsevier
artmeta generate -j elsarticle --insert elsevier_version/main.tex

# Générer pour Springer
artmeta generate -j svjour3 --insert springer_version/main.tex

Cas d'usage avancés¶

Utiliser plusieurs affiliations¶

authors:
  - firstname: "Marie"
    lastname: "Curie"
    affiliations: [1, 2]  # Deux affiliations
    email: "marie@univ.fr"

affiliations:
  - id: 1
    name: "Institut du Radium"
    institution: "Université Paris"

  - id: 2
    name: "Laboratoire de Physique"
    institution: "Sorbonne"

Le code LaTeX généré adapte automatiquement le format selon la classe : - amsart : Multiple \address commands - elsarticle : \author[1,2]{Marie Curie} - svjour3 : \institute{...}

Intégration CI/CD¶

Validez automatiquement vos métadonnées dans votre pipeline CI/CD :

GitHub Actions :

# .github/workflows/validate.yml
name: Validate metadata

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install artmeta
        run: pip install artmeta
      - name: Validate metadata
        run: artmeta validate

GitLab CI :

# .gitlab-ci.yml
validate:
  image: python:3.10
  script:
    - pip install artmeta
    - artmeta validate

Scripts de génération automatique¶

Automatisez la génération de toutes les versions :

#!/bin/bash
# generate_all.sh

CLASSES="amsart elsarticle svjour3 siamart"

for class in $CLASSES; do
    echo "Generating $class version..."
    mkdir -p output/$class
    artmeta generate -j $class -o output/$class/metadata.tex

    # Créer un fichier LaTeX complet
    cat > output/$class/main.tex << EOF
\documentclass{$class}

$(cat output/$class/metadata.tex)

\begin{document}
\input{content.tex}
\end{document}
EOF
done

echo "All versions generated in output/"

Validation personnalisée¶

Vous pouvez valider votre fichier programmatiquement :

from artmeta.validators import validate_metadata
import yaml

with open('art.yml') as f:
    meta = yaml.safe_load(f)

errors = validate_metadata(meta)

if errors:
    print("Erreurs de validation:")
    for error in errors:
        print(f"  - {error}")
else:
    print("Validation réussie!")

Bonnes pratiques¶

1. Versionnez vos métadonnées¶

Incluez art.yml dans votre dépôt Git :

git add art.yml
git commit -m "Update metadata with new coauthor"

2. Utilisez des noms de fichiers descriptifs¶

# Plutôt que art.yml
artmeta init -o neurips2024_paper.yml
artmeta init -o jmlr_submission.yml

3. Validez toujours avant de générer¶

# Toujours faire
artmeta validate && artmeta generate -j amsart --insert main.tex

# Plutôt que
artmeta generate -j amsart --insert main.tex  # Peut échouer silencieusement

4. Gardez une copie de sauvegarde¶

cp art.yml art.yml.backup

5. Utilisez des commentaires YAML¶

# Article soumis à JMLR en octobre 2024
title: "Deep Learning for Time Series"

authors:
  # Auteur principal
  - firstname: "Alice"
    lastname: "Martin"
    # ...

Prochaines étapes¶

Consulter le Guide de contribution si vous voulez ajouter une nouvelle classe de revue
Voir le Changelog pour les nouveautés de chaque version

Guide utilisateur¶

Table des matières¶

Démarrage rapide¶

1. Créer un fichier de métadonnées¶

2. Éditer vos métadonnées¶

3. Valider¶

4. Générer le code LaTeX¶

5. Insérer dans votre fichier .tex¶

Format du fichier YAML¶

Champs disponibles¶

Champs obligatoires¶

Champs optionnels¶

Structure d'un auteur¶

Structure d'une affiliation¶

Exemple complet¶

Commandes disponibles¶

artmeta init¶

artmeta validate¶

artmeta info¶

artmeta stats¶

artmeta generate¶

artmeta switch¶

artmeta hal-xml¶

Workflows typiques¶

Workflow 1 : Soumission à une revue AMS¶

Workflow 2 : Changer de revue¶

Workflow 3 : Soumission HAL¶

Workflow 4 : Plusieurs versions simultanées¶

Cas d'usage avancés¶

Utiliser plusieurs affiliations¶

Intégration CI/CD¶

Scripts de génération automatique¶

Validation personnalisée¶

Bonnes pratiques¶

1. Versionnez vos métadonnées¶

2. Utilisez des noms de fichiers descriptifs¶

3. Validez toujours avant de générer¶

4. Gardez une copie de sauvegarde¶

5. Utilisez des commentaires YAML¶

Prochaines étapes¶

`artmeta init`¶

`artmeta validate`¶

`artmeta info`¶

`artmeta stats`¶

`artmeta generate`¶

`artmeta switch`¶

`artmeta hal-xml`¶