Comment créer une documentation PDF avec des extraits de code à copier-coller?

Question

J'ai essayé d'utiliser LaTeX et DocBook pour documenter des outils de programmation, pour obtenir des sorties PDF. Ce que j'ai trouvé, c'est que ces outils sont excellents à certains égards - facilement versionnables, et générant des manuels PDF très utilisables. Mais il y a un défaut sérieux. Les extraits de code ne peuvent pas simplement être coupés et collés hors du PDF. Avec DocBook, le problème est la perte d'espaces - principalement pour l'indentation, mais tous les espaces répétés semblent être supprimés. Ainsi, une fois que vous avez collé l'extrait dans un éditeur de texte, vous devez nettoyer l'indentation et l'alignement vertical. Pas trop de tracas pour deux ou trois lignes, mais ça devient vite énervant.

Avec LaTeX - eh bien, c'est un gâchis. Ce qui suit a été tiré d'un PDF généré en utilisant le LaTeX dans MikTeX 2.8.

node myclas s 
f f i e l d f i e l d 0 1 : i n t ; 
f i e l d f i e l d 0 2 : ” char ” ; 
g; 

L'exemple est prévu ...

node myclass 
{ 
    field field01 : int; 
    field field02 : "char*"; 
}; 

Autre que le fait LATEX joue avec les guillemets, la forme prévue est ce que vous voyez dans Adobe Reader - mais pas beaucoup ce que vous obtenez de un couper-coller. Ne me demandez pas ce qui se passe avec les espaces, ou pourquoi les accolades se sont transformées en lettres, ou ce qui est arrivé à l'astérisque - je ne sais pas! La plupart du temps, j'ai remarqué ces choses en jouant avec des façons de garder mes propres notes personnelles, et je suis simplement retourné à d'autres façons. Certaines notes sont en HTML ou en texte brut, donc je peux les versionner. D'autres sont dans un vieux programme Journal que j'ai utilisé pendant des années. Mais j'ai écrit un outil que je pourrais bientôt publier - et je voudrais inclure un manuel PDF utilisable, qui devra inclure des exemples. Donc, y a-t-il un moyen de créer une documentation PDF dans laquelle les extraits de code peuvent être facilement copiés-collés? De préférence un moyen qui me permet de garder des "sources" dans les fichiers texte versionnés.

EDIT

Toute solution doit être portable. Je vais devoir l'utiliser sous Linux et Windows XP.

EDIT

Il ressemble à ceci peut être impossible.

J'ai essayé d'imprimer à partir du Notepad ++ vers le pilote d'imprimante Adobe Acrobat Pro 7. Le document qui en résulte a l'air bien, mais couper et coller a donné les mêmes problèmes d'espaces manquants qui se produisent avec DocBook.

J'ai essayé d'utiliser l'outil de retouche de texte dans Acrobat Pro pour ajouter des espaces de premier plan. Ceux-ci sont conservés lorsque vous enregistrez et rechargez - mais lorsque vous sélectionnez normalement du texte dans acrobat, ils ne sont pas inclus. Vous pouvez seulement copier-coller, y compris ces espaces, en utilisant l'outil de retouche de texte, pour autant que je sache, qui n'est évidemment pas inclus dans le lecteur. En d'autres termes, cela ressemble à une limitation fondamentale - pas du format PDF lui-même autant que les outils qui fonctionnent avec elle. Il semble y avoir une supposition générale à l'œuvre ici que les espaces blancs sont insignifiants - ce qui, à mes yeux, n'est évidemment pas vrai.

EDIT

Une solution peut être un "champ de texte".Je peux les ajouter assez facilement en utilisant Acrobat Pro, je peux définir une police de largeur fixe, entrer plusieurs lignes de texte et rendre le champ en lecture seule. Dans Acrobat Pro 7, le texte dans le champ n'est pas sélectionnable, mais dans Reader 9, est sélectionnable et tout est conservé lorsque vous coupez et collez.

La question est - les champs de texte peuvent-ils être générés directement en utilisant un langage de balisage qui est utilisable pour créer des manuels complets?

Answer 1

Je suggérerais enscript. Je l'utilise pour produire des archives et des documentations. En outre, vous pouvez fusionner plusieurs codes source ps'ed avec enscript dans un autre fichier pdf.

Answer 2

Si votre code est conservé dans des fichiers externes, l'un des moyens consiste à joindre le (s) fichier (s) d'origine en tant que pièces jointes PDF. Cela pourrait être fait avec Docbook, LaTeX, DITA, et quelques autres. Par exemple, si vous utilisez this method to include code in Docbook, vous pouvez écrire du code dans votre couche de personnalisation XSL pour ajouter le fichier externe en pièce jointe au PDF. Pour autant que je sache, c'est portable (bien que je n'ai pas personnellement essayé d'ouvrir des fichiers PDF avec des pièces jointes dans Evince, Okular, Xpdf, etc pour voir ce qui se passe).

Si vous traitez les fichiers Docbook en utilisant FOP, vous devriez toujours pouvoir écrire quelque chose dans votre couche de personnalisation pour joindre des fichiers. Voir le section on PDF attachments. Vous pouvez même afficher un lien vers la pièce jointe sous le bloc de code dans le fichier PDF si vous souhaitez le rendre plus accessible aux personnes.

Une solution similaire devrait être possible en utilisant LaTeX avec le paquet attachfile.