Envie d'essayer le Typographe ?

Pour des raisons d'ordre pratique (affichage des codes sources d'un serveur), cette page n'est pas mise en forme avec le Typographe. Vous pouvez donc y trouver des aberrations que le Typographe corrige normalement.

Vous voulez utiliser le Typographe sur votre site Web ? C'est très simple, suivez le guide !

Installation

Étape 1 : création du conteneur

Il vous suffit de créer un nouveau dossier sur votre site qui contiendra l'ensemble des fichiers. Nommez-le par exemple "Typo".

Étape 2 : récupération du contenu

Le Typographe inclut un module de mise à jour automatique. Il vous suffit donc de télécharger le fichier gérant la Mise À Jour pour récupérer la version la plus à jour du Typographe. Le code source du fichier est juste en-dessous :

Code source : MAJ_client.php

<?php

define('MASTER','http://neamar.fr/lib/Typo/');



error_reporting(E_ALL);

$Mute=false;



//Ne pas effectuer la Màj sur le serveur maitre

if($_SERVER['SERVER_NAME']=='neamar.fr')

	exit();



function browseFiles($Dir,&$Tree)

{

	$Exclus=array('.','..');

	$dir_handle = opendir($Dir);

	while ($file = readdir($dir_handle))

	{

		if(!in_array($file,$Exclus))

		{

			if(is_dir($file))

				browseFiles($Dir . '/' . $file,$Tree);

			else

			{

				//Remplacer les . par des @ car les . ne passent pas le POST.

				$Key=preg_replace('#\.([a-z]+)#','@$1',str_replace('./',"",$Dir . '/' . $file));

				$Tree[$Key]=filemtime($Dir . '/' . $file);

			}

		}

	}

}



//Télécharge $URL avec les données $POST demandées.

function download($URL,$POST=array())

{

	$POST_str="";//La chaine de caractères du POST mis à plat

	foreach($POST as $k=>$v)

		$POST_str .= urlencode($k) . '=' . urlencode($v) . '&';

	rtrim($POST_str,'&');//Supprimer la dernière Esperluette



	//Intialiser une connexion avec CURL pour récupérer les données demandées

	$Connexion = curl_init();

	curl_setopt($Connexion, CURLOPT_URL,MASTER . $URL);

	curl_setopt($Connexion, CURLOPT_RETURNTRANSFER, 1);

	curl_setopt($Connexion,CURLOPT_POST,count($POST));

	curl_setopt($Connexion,CURLOPT_POSTFIELDS,$POST_str);

	$retour = curl_exec($Connexion);

	curl_close($Connexion);//Nettoyer

	unset($Connexion);

	return $retour;

}



//Affiche un message

function Out($texte)

{

	global $Mute;

	if(!$Mute)

		echo '<p>' . preg_replace('#{(.+)}#','<strong>$1</strong>',$texte) . "</p>\n";

}



Out("Lancement de la mise à jour du {Typographe}.");

//Liste des fichiers actuellement sur le serveur

$Tree=array();

browseFiles('.',$Tree);

asort($Tree);





///PREMIÈRE ÉTAPE : fichiers modifiés.

//Préparer une requête POST :

$Files=unserialize(download('MAJ_server.php?CheckNewVersion',$Tree));

//La requête renvoie la liste des fichiers plus récents que ceux actuellement sur le serveur

if(count($Files)!=0)

{//Il y a eu des modifs, il va falloir télécharger tout ça.

	Out('Le script va effectuer la mise à jour de ' . count($Files) .  ' fichier(s) (' . implode(', ',$Files) . ')');

	///SECONDE ÉTAPE : repartir sur une arborescence saine

	$Dirs=unserialize(download('MAJ_server.php?GetDirs'));

	Out("Liste des dossiers récupérée");

	//Récupérer tous les nouveaux dossiers et les créer si nécessaire.

	foreach($Dirs as $Dir)

	{

		if(!is_dir($Dir))

		{

			Out("Création d'un nouveau répértoire : {" . $Dir . '}');

			mkdir($Dir);

		}

	}



	///TROISIÈME PARTIE : charger chacune des pages nécessaires.

	foreach($Files as $File)

	{

		Out('Téléchargement du fichier {' . $File . '}');

		file_put_contents($File,download('MAJ_server.php?GetCode',array('File'=>$File)));

		Out("Fichier {" . $File . '} enregistré.');

	}

	Out("Fin de la mise à jour.");

}

else

	Out('La version du Typographe installée sur le serveur {' . $_SERVER['SERVER_NAME'] . '} est à jour.');

Enregistrez ce document sous le nom MAJ_client.php dans votre répértoire crée à l'étape 1.

Étape 3 : téléchargement des données

Exécutez maintenant le fichier MAJ_client.php en l'appelant depuis votre navigateur (e.g. http://votresite.fr/Typo/MAJ_client.php).
Vous devriez avoir alors des messages vous informant de la progression de la mise à jour. Une fois le script terminé, regardez dans votre FTP le dossier Typo qui a dû se remplir de données.

L'installation est alors terminée.

Utilisation

Initialisation

Sur chaque page où vous souhaitez utiliser le Typographe, vous devrez :

Inclure le code source du Typographe au début de chaque page qui doit l'utiliser (ou dans votre header.php pour une utilisation sur toutes les pages) :
Code source : Inclusion Typographe
```
include('Chemin/Vers/Typo/Typo.php');
```
Inclure la feuille de style de base du Typographe dans votre HTML (Chemin/Vers/Typo/Typo.css). Notez que son utilisation n'est pas obligatoire mais fortement recommandée ; en effet la feuille ne définit pas de mise en forme au sens graphique mais plus les conventions typographiques : par exemple, afficher un "Résumé" au dessus des environnements abstracts, enlever l'emphase à l'intérieur d'une autre emphase, etc. :
Code source : CSS Typographe
```
<link rel="stylesheet" type="text/css" href="https://neamar.fr/lib/Typo/Typo.css" />
```

Utilisation

L'utilisation du Typographe se fait en deux temps : premièrement, régler le texte, ensuite, demander une sortie mise en forme.

Régler le texte

Deux méthodes sont disponibles : Typo::setTexte($Texte); et Typo::setTexteFromFile($Fichier);. Si le texte n'est pas un string, ou si le fichier n'existe pas, une erreur sera déclenchée : vous pouvez supprimer ce comportement en activant l'option RAISE_NO_ERROR, mais ceci est fortement déconseillé.

Récupérer la sortie

Une fois le texte enregistré en mémoire, vous pouvez le récupérer de trois façons différentes :

La première et la plus courante se fait avec Typo::Parse() qui renverra alors un chaine de caractères au format HTML.
La seconde option est de récupérer un texte "plat" : toutes les balises seront alors négligées, mais les ligatures, tirets, guillemets et autres seront correctement formatés. Ceci peut être utile pour afficher une version "light" du texte.
Dernière option : afficher le texte en mode édition avec Typo::renderIDE(). Le Typographe dessine alors un IDE complet pour mettre en forme le texte. L'intégration de l'IDE est définie plus loin, ainsi que les options disponibles.

Exemple d'utilisation

Voici un exemple d'utilisation basique :

Code source : Exemple d'utilisation



include('Chemin/Vers/Typo/Typo.php');

Typo::setTexte('Ceci est un texte exemple, avec un minimum de mise en forme - ceci est, par exemple,

en \b{gras} tandis que ceci est en \i{italique}.');



//Renvoie :

//<p>Ceci est un texte exemple, avec un minimum de mise en forme &ndash; ceci est, par exemple,

//en <strong>gras</strong> tandis que ceci est en <em>italique</em>. </p>

echo Typo::Parse();

Pour aller plus loin...

Cette étape est facultative.

Mise à jour

Le Typographe est en mutation constante.
Vous pouvez remettre à jour la version dont vous disposer en appelant à nouveau le fichier MAJ_client.php : si des nouveautés sont disponibles, la mise à jour sera automatiquement effectuée.
Si vous ne souhaitez pas laisser un accès à votre site, pensez à supprimer le fichier MAJ_client.php qui peut potentiellement être une faille de sécurité.

Configuration

Il se peut que la configuration par défaut ne vous plaise pas. Vous disposez d'un ensemble d'options pour transformer le Typographe en module agréable.

Consultez les premières lignes du fichier Typo.php pour voir les options disponibles.

Voici par exemple la configuration pour écrire un texte en anglais, en interdisant les balises titres, en utilisant le moteur mathématique et en affichant les footnotes entre parenthèses:

Code source : Configuration d'exemple



Typo::switchLanguage("en");



//Les textes entre $ seront remplacés par leur équivalent LaTeX.

Typo::addOption(PARSE_MATH);



//removeOption supprime l'option : les \section, \subsection et autres ne seront pas remplacés.

Typo::removeOption(ALLOW_SECTIONING);



//Pour que les notes de bas de page soient entourées de parenthèses,

//ce qui évite de les confondre avec des puissances mathématiques.

Typo::addOption(ALLOW_FOOTNOTE,FOOTNOTE_SCIENCE);

Langage

Chaque langue a ses propres règles typographiques. Le Typographe fournit des fichiers de configuration indiquant de quelle façon le texte doit être rendu.
Par défaut, le Typographe charge les fichiers de configuration pour la langue française.

Code source : Exemple d'utilisation des langues



Typo::setTexte('Une phrase,sans règles;qui sera correctement - enfin normalement - mise en forme selon les standards du pays !');

echo Typo::parseLinear();

Typo::switchLanguage('en');

echo Typo::parseLinear();

Ce qui renverra :
Une phrase, sans règles ; qui sera correctement – enfin normalement – mise en forme selon les standards du pays ! Une phrase, sans règles; qui sera correctement—enfin normalement—mise en forme selon les standards du pays!

Ajout de balises

Si vous le souhaitez, vous pouvez ajouter de nouvelles balises ou en supprimer certaines. Attention, ceci nécessite une connaissance des expressions régulières !
La liste des balises par défaut se trouve dans le fichier Lng/fr.php. Ne modifiez pas cette liste, car le fichier peut être écrasé à tout moment par une mise à jour : préférez donc utiliser la méthode addBalise().

Code source : Exemple de configuration des balises



//Redéfinir la balise \ref pour effectuer un lien vers un article précis plutôt que vers une section de la page.

Typo::addBalise('#\\ref\[(.+)\]{(.+)}#isU','<a href="/O/$1">$2</a>');



//Définir une nouvelle balise.

Typo::addBalise('#\\sagaref\[(.+)\]{(.+)}#isU','<a href="/Liste/$1">$2</a>');

IDE

L'affichage de l'IDE peut être personnalisé en envoyant en paramètres un tableau d'options. Ceci permet par exemple de définir un bouton affichant dynamiquement un apercu du texte.

Code source : Exemple de configuration de l'IDE



Typo::setTexteFromFile('UnFichierTexte.txt');

//Si aucun paramètre n'est spécifié, l'IDE est affiché avec le name Texte, 10 lignes et 25 colonnes.

//Ici, on écrase les paramètres par défaut.

Typo::renderIDE(array('Name'=>'Editeur','Rows'=>20,'Cols'=>15));

Comme dit plus haut, vous pouvez configurer un module d'affichage pour un aperçu. Ceci se passe via l'option Preview du tableau d'options :

Code source : Exemple de configuration de l'IDE



Typo::setTexte($News);

//Les paramètres doivent inclure :

// - L'url à appeler (les données sont fournies via la méthode POST, variable Texte : c'est à vous de les traiter.

//  Le plus souvent, un simple Typo::Parse(); suffit.

// - L'ID de l'élément  HTML dans lequel le résultat doit être affiché.

Typo::renderIDE(array(

	'Name'=>'texte-' . $ID,

	'Rows'=>30,

	'Preview'=>array(

		'URL'=>'/membres/preview.php',

		'ID'=>'Typo_preview-' . $ID

		)

	)

);

Pour aller plus loin...

Si vous ne trouviez pas votre bonheur dans cette rapide présentation, vous pouvez me contacter.