26

I just took all the wonderful information supplied here, and wrote a small package that makes it possible to use Unicode characters for section, subsection, subsubsection, paragraph, subparagraph and item. I think it makes the text look neat, and it might be very useful for RTL users.

\NeedsTeXFormat{LaTeX2e}
\ProvidesPakcage{usection}
    {2011/02/07 Unicode characters instead of section, subsection, etc.}
\newcommand*{\toEolnCommand}[2]{%
  \newcommand*{#1}{%
    \begingroup%
    \escapechar=`\\%
    \catcode\endlinechar=\active%
    \csname\string#1\endcsname%
  }%
  \begingroup%
  \escapechar=`\\%
  \lccode`\~=\endlinechar%
  \lowercase{%
    \expandafter\endgroup
    \expandafter\newcommand\csname\string#1\endcsname##1~%
  }{\endgroup#2\space}%
}

\toEolnCommand\toEolnSection{\section{#1}}
\toEolnCommand\toEolnSubsection{\subsection{#1}}
\toEolnCommand\toEolnSubsubsection{\subsubsection{#1}}
\toEolnCommand\toEolnParagraph{\paragraph{#1}}
\toEolnCommand\toEolnSubparagraph{\subparagraph{#1}}

\catcode"2022=\active \newcommand•{\item}         % Bullet
\catcode"B6=\active  \newcommandf¶{\@xparagraph} % ¶: U+00B6 PILCROW SIGN
\catcode"A7=\active  \newcommand§{\@xsection}       % §:  U+00A7 SECTION SIGN


\newcommand\@xparagraph{%
      \@ifnextchar ¶ {%
                \expandafter
                \toEolnSubparagraph
                \@discardNextChar
      }{%
              \toEolnParagraph
      }%
}

\newcommand\@xsection{%
  \@ifnextchar§{% Two or more § were found.
      \expandafter
      \@sub@or@subsub@section
      \@discardNextChar%
   }{% Single § found.
      \toEolnSection
  }
}

\newcommand\@sub@or@subsub@section{
      \@ifnextchar§{%
        \expandafter
        \toEolnSubsubsection
        \@discardNextChar
      }{%
          \toEolnSubsection
      }%
}


\newcommand\@discardNextChar#1{}

So, (a) do you think I should publish this, and if yes, (b) how should I do so?

EDIT I correct my question to make it useful to the general public: (a) What are the cirteria to be applied in considering a package worthy of publications and (b) which steps should be taken to realizing such a decision?

Yossi Gil
  • 15,951
  • 5
    You are trying to ask two questions at the same time (I think). One is about how to publish/promote a package, and the other is perhaps about getting feedback on the particular package you wrote. I think that both questions are quite good questions! But the answers will be probably most useful to you (and the community in general), if you ask these two questions separately. – Juan A. Navarro Feb 08 '11 at 14:11
  • 3
    I think the first thing you should to if you decide to publish it is write some documentation, with examples. Look at ftp://indian.cse.msu.edu/pub/mirrors/CTAN/info/dtxtut/dtxtut.pdf for a tutorial on creating documented TeX source files. – Jan Hlavacek Feb 08 '11 at 14:25
  • BTW: You are missing a % behind { inside the \@sub@or@subsub@section and behind a } in \@xsection (ok \@ifnextchar will gobble it, but anyway). – Martin Scharrer Feb 08 '11 at 15:07
  • 2
    You should also make sure that all your macro names, espacially the internal ones, are unique. This is most commonly done by using the (maybe shortened) package name followed by @ as prefix. Example: \usection@xsection instead of \@xsection which might be already defined by another package. – Martin Scharrer Feb 08 '11 at 15:09
  • 3
    @Martin: Although it's common to prefix macros with the package name and @, I realized recently that it's much better to suffix them. That way, if you index your documentation (which you should do), the alphabetization is meaningful. – Ryan Reich Feb 08 '11 at 16:00
  • @Ryan: Good point. I for myself prefer PDF search before the index. It should be possible to remove the prefix before alphabetization. – Martin Scharrer Feb 08 '11 at 16:16
  • @Martin: If it is possible, I'd like to know how (using, for example, \begin{macro}{\mypackage@mymacro}...\end{macro}). This irked me greatly when I did the documentation for ytableau. As for PDF search, I think the index, if done right, is more helpful because it points you straight to the definition and description before any of the many many instances of its use. – Ryan Reich Feb 08 '11 at 17:28

2 Answers2

30

To (a): why not, as long it is useful for a hand of people its worth the HD space on the CTAN servers

To (b): You should do the following steps

  1. Convert it to a .dtx file, either manually (see dtxtut) or using sty2dtx.
  2. Place it under the LaTeX project public license, i.e. add the license statement and your copyright.
  3. Add some user documentation, i.e. describe for what the package is useful for and how to use the macros, plus some visual examples. You should also document the code and explain how it is implemented so that other people (and you after a while) can understand how it works.
  4. ZIP the .dtx, .ins and the generated .sty and PDF as well as a short README together. The ctanify tool is also very useful for this.
  5. Upload it on CTAN with some announcement text.

I published a couple of packages this way.

Martin Scharrer
  • 262,582
  • 5
    It is not mandatory to make a dtx+ins or a pdf-documentation. You can also simply upload a sty and a readme as documentation (or even put the documentation after \endinput in the sty itself). – Ulrike Fischer Feb 08 '11 at 14:48
  • 4
    True it is not mandatory for acceptance on CTAN, but I would recommend it. It should be pretty easy with sty2dtx anyway and having a PDF on CTAN simplifies things a lot for people which looking for the documentation online. @Ulrike – Martin Scharrer Feb 08 '11 at 14:53
  • 1
    @Ulrike — I don't think this is true any more regarding the lack of PDF documentation. The CTAN (or perhaps TL) maintainers have even gone back through the old packages without PDF documentation and created it manually. (E.g., see texdoc printlen, which was not created by me.) – Will Robertson Feb 08 '11 at 14:54
  • 2
    @Martin: This sty2dtx tool of yours seems pretty handy, thanks :). – Bruno Le Floch Feb 08 '11 at 15:03
  • @Bruno: Thanks. I still have to write some PDF documentation for it ;-) Note that you can define your own templates for the generated files. – Martin Scharrer Feb 08 '11 at 15:14
  • 2
    I think that as part of point 1, when you convert it to .dtx you should document the code. Well-documented packages are fun to read, sparsely-documented ones are frustrating. Undocumented ones are worthless for learning, and that's a shame since I've learned a lot from reading, say, the verbatim package. – Ryan Reich Feb 08 '11 at 17:44
  • @Ryan: I was going to mentioned that under 3. but forget then about it. I will add it now. Note that 1. is just creating the outer DTX format, not yet the content. – Martin Scharrer Feb 08 '11 at 18:00
13

Martin has already explained quite well how to publish a package.

I think there is scope for a package that can make characters active and assign meanings to them. (I've thought about writing something similar before, actually.) But there are some tricky things to consider, and I think it is confusing the issue to start changing LaTeX markup at the same time — if your package also changes •, ¶, § in text then this, IMO, should be customisable. You mention it's useful for RTL users, but as I recall you're editing your TeX files in OpenOffice, which I suspect is somewhat unusual.

I'm also not entirely sure how robust these "grab until end-of-line" commands are. (Consider \foo{¶ something}.) But if you're only dealing with \section and so on I guess it's not too much of a problem.

If you only intend to keep the code as-is in its fairly specific form, I'd suggest not publishing it for the time being while you use it for your own work. If it does turn out to be quite useful to you over time then, yes, I would consider polishing it up and submitting it to CTAN.

Will Robertson
  • 73,872
  • 8
    I think this is a very important point that you make: do not publish until you found it useful for you, and experimented with it for a little bit. – Yossi Gil Feb 08 '11 at 17:07
  • could be made outer, since one can still use \paragraph and the like if a non-outer macro is needed. – Bruno Le Floch Feb 09 '11 at 03:55
  • @Bruno: there's one for http://tex.stackexchange.com/questions/2012/when-is-it-appropriate-to-use-outer/8115#8115! – Ryan Reich Feb 09 '11 at 14:22