Haskell lettré (.lhs) et Haddock

Question

Pour le moment je suis le seul à l'aide de l'Aiglefin, mais après avoir vu quelques exemples très intéressants (par exemple, ce gist ) d'alphabétisation des Haskell je suis intéressé à essayer dans un projet.

Les questions que j'ai eu sont:

• Que pensez-vous écrire que l'Églefin commentaires et ce que vous écrivez dans l'écriture de la partie?

• Comment pensez-vous de l'échelle lettrés de la programmation de plusieurs fichiers? Quelqu'un peut-il m'indiquer un exemple où les lettrés de programmation est utilisé dans un package avec plusieurs modules? Quelle est votre expérience de l'utilisation de lettrés de la programmation dans de plus gros paquets?

• Quelle saveur (markdown, latex, ...) d'alphabétisation des Haskell est-il préférable?

• Pourquoi êtes-vous de la programmation alphabétisés Haskell ou de la plaine à la vanille Haskell? Êtes-vous de la programmation dans les deux styles, et si oui, pourquoi?

• Préférez-vous le bloc-style (\begin{code}) ou d'Oiseaux de style (>)? Pourquoi?

Answer 1

J'ai utilisé pour écrire beaucoup de lettrés programmes.

Que pensez-vous écrire que l'Églefin commentaires et ce que vous écrivez dans l'écriture de la partie?

L' externe de documentation de l'API va dans le Haddock commentaires. Tout le reste va dans l'écriture de la partie. "Tout le reste" peut inclure:

• Interne invariants de structures de données
• Pourquoi vous faites les choses de cette façon
• Ce que la conception du code est
• Pourquoi ce design a été choisi, ce que d'autres modèles ont été essayé et ont trouvé preneur

Comment pensez-vous de l'échelle lettrés de la programmation de plusieurs fichiers?

De la même manière que l'échelle d'un grand document LaTeX de plusieurs fichiers: un fichier par module, puis un géant fichier \includes tous.

Quelqu'un peut-il m'indiquer un exemple où les lettrés de programmation est utilisé dans un package avec plusieurs modules?

Ce n'est pas Haskell, mais la C Rapide-- compilateur est un grand programme fonctionnel qui est écrit à l'aide de lettrés de la programmation.

Quelle est votre expérience de l'utilisation de lettrés de la programmation dans de plus gros paquets?

Lettré de programmation fonctionne très bien pour la documentation délicat, difficile, ou des modules complexes. Pour la plupart des modules simples, l'API externe de documentation (par exemple, l'Aiglefin) est suffisant. Et aucun lettré programme est vraiment vous donner la grande image, d'un dessin ou modèle qui contient plus d'une douzaine de modules. Pour cela vous avez besoin d'autres outils et techniques.

Quelle saveur (markdown, latex, ...) d'alphabétisation des Haskell est-il préférable?

Si vous êtes à la fabrication d'un tel investissement majeur, je serais certainement aller avec le LaTeX et simplement parce que le calcul de la capacité, et généralement une plus grande puissance de l'outil.

Pourquoi êtes-vous de la programmation alphabétisés Haskell ou de la plaine à la vanille Haskell? Êtes-vous de la programmation dans les deux styles, et si oui, pourquoi?

Mon Haskell codes sont presque toujours tous les classiques, pour deux raisons:

• Je travaille avec des personnes âgées qui ont plus de Haskell expérience, et ils ont abandonné le lettré Haskell. Seuls les plus anciens des modules dans leur système ont aucune chance de l'être .de gauche.

• Pour Haskell, lettré de la programmation est une sorte de superflu. Un des grands avantages d'une culture de la programmation de l'outil, c'est que vous êtes libéré de toutes les contraintes que le compilateur du langage ou de définition pourrait mettre de l'ordre dans lequel votre code s'affiche. Mais Haskell n'a presque pas de telles contraintes: il n'y a pas de définition avant de l'utiliser, et pour un type de définition de fonction, j'ai le choix d' let-la liaison ou l' where-liaison auxiliaire de noms (ou les deux). Lettré de la programmation n'a jamais été juste au sujet de fantaisie commentaires, et avec des "lettrés" Haskell c'est tout ce que vous obtenez. Il n'en vaut pas la peine.

Préférez-vous le bloc-style (\begin{code}) ou d'Oiseaux de style (>)? Pourquoi?

Je préfère largement bloc de style:

• C'est à peu près compatible avec tous les autres lettrés-outil de programmation sur la planète. (Les pistes sont uniques à Haskell.)

• Mon éditeur s'adapte mieux avec bloc de style.

Answer 2

Si vous avez l'intention de partager des programmes sur l'internet, j'ai trouvé une combinaison de lettré haskell en markdown style avec mathjax pour être une grande combinaison. Le programme "Pandoc" est sérieusement brillant pour la prise de ce "markdown+lhs" à n'importe quel format que vous désirez, y compris au format PDF ou HTML. Si vous dites à Pandoc pour la sortie au format HTML, vous pouvez utiliser l'-mathjax (ou d'autres drapeaux si vous préférez) pour avoir vos formules mathématiques en latex de rendu.

Lors de l'utilisation de ce style, je trouve oiseau style préférable, parce qu'il est plus lisible pour moi et semble s'adapter avec la minoration de style mieux.

La grande chose sur l'utilisation de Pandoc avec markdown, c'est que vous pouvez ajouter des citations à votre code, les formules mathématiques, et ont vraiment un format portable. Vous pouvez construire quelque chose qui ressemble à un scientifique, document de recherche, mais est exécutable et peuvent également être publiés sur les blogs/wikis/sites web.

Pour donner un autre point de Norman où il dit que les lettrés de la programmation est utile pour le code plus clair arrangement, il pourrait être soutenu que Haskell est assez expressif que les problèmes à résoudre avec le code sont réellement intéressant et peut vraiment bénéficier en étant entouré avec un texte explicatif. Pensez à une recherche mathématique de papier. Articles de mathématiques pures ont beaucoup de texte à expliquer la motivation ou à un niveau supérieur interprétations de ce que la notation mathématique moyens. Dans un article sur les équations de Navier-Stokes, par exemple, il serait super utile pour entourer la notation des équations avec un texte expliquant comment il se rapporte à Newton la conservation de l'impulsion.

En résumé, j'ai eu un bon succès avec, et de recommander, en utilisant markdown+lhs style, le signe du dollar pour intégrer des formules mathématiques en latex, d'oiseaux, de style, et pandoc. Je recommanderais l'écriture de programmes, comme s'ils étaient des documents de recherche et de traiter le haskell lui-même comme vous le feriez d'expressions mathématiques dans un document de recherche.