3

Background

I have lately been thinking about contributing to CTAN. This question has many nice links in that regard.

However: I've noticed that most (if not all) of the packages have the same documentation layout. So I started doing some research on this and came across Documented LaTeX Format, and I had a few questions regarding how it's commonly applied.

This answer suggests that you don't have to document a package using docstrip, and I haven't come across anywhere it says that it has to be this format.

CTAN's dtx tutorial is a nice introduction to the syntax, and I think I got that part covered. My specific questions are:

What I would like to know

  1. Is it common to write documentation separately from your file (illiterate(?))?
  2. If you ever wrote a package that could be published to CTAN, how did you go about documentation?
  3. Anything related to this that I should know about?
  4. The TeX FAQ mentions "sty2dtx" which "attempts to create a dtx file from a ‘normal’ sty file with comments.". Is this something you've tried? Does it work well?
  5. What are good alternatives for generating .dtx-files from .sty-files

Anything related to this that I should know is very well appreciated.

Edit: I could mention that I would only write packages that are related to statistics, math, physics and the like.

Improve this question
1
  • Comments are not for extended discussion; this conversation has been moved to chat. Commented Mar 28, 2018 at 17:10

2 Answers 2

Reset to default
4

CTAN does not require a dtx file. CTAN requires a documentation -- in most cases a PDF file. How you produce it is up to you.

Nevertheless the de facto standard for LaTeX packages is to wrap them into a dtx file. In the simplest case this means taking your sty file and add some comments before and after your code. The details are described in the documentation you have cited already.

I have done it and it is more fun than pain;-) I have never felt that I need a tool to support me. Writing LaTeX code even if it appears in comments ist simple enough.

Improve this answer
1

In general I write (documented) code using doc/docstrip. From a single source I can generate a User Manual, Documented Code, and Plain Code. This has made maintenance and code extensions relatively easy as everything is in one place rather than having to remember to update N other files.

I was so comfortable with this that, lost in the midst of time when I was a paid employee, I extended the doc/docstrip system to cater for other programming languages such as Metafont/Metapost. C and EXPRESS (an ISO 10404 Information modelling language I helped to develop).

It really enabled me to keep everything in one place. In the case of the memoir class I wrote a separate User Manual because of the size of the overall documentation; effectively I split a 2000- page document into two reasonably sized productions aimed at different audiences.

Improve this answer
3
  • Yes, but... Without further intervention, a generated user manual has the disadvantage that it is PDF. I opine that a better format is HTML, which does not involve page breaks, and does not need to float materials to a distant page. Also allows stand-alone images. This is what Adobe does for its products. What does Adobe know about PDF that TeX does not know? Commented Mar 27, 2018 at 23:35
  • @RobtAll TeX is a system designed specifically for producing the printed page. Creating an HTML manual might work for some things, but in contexts where the typeset output is the point of the package, having documentation in HTML defeats that purpose, and makes things harder. For example, any math would need to be turned into images to be rendered etc. Adobe produces web manuals because people expect them and they have loads of cash. TeX contributers are all volunteers who don't. It's not about what they do or don't know about PDF. Commented Mar 27, 2018 at 23:56
  • @AlanMunn Umm.. As the creator of the novel package, which is all about producing the printed page, I nevertheless wrote the documentation in HTML. However, I don't do math. Never read a math book. :) Commented Mar 28, 2018 at 0:04

You must log in to answer this question.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.