0

I come to you today with an open question instead of a precise and technical one. I have tried many different packages in the past, each time I have to take a dive into the documentation. Those packages are without a doubt the results of hours and days of work, and still those who produce them, refuse to start their explanation by what seems to me like the the most evident piece of information essential to anyone starting to use a new numerical tool: a minimal working example.

I could start a rant of insults for those men who made me lose so many hours because they won't do that simple thing. Can you explain to me what I am missing here? If it were only one I would curse their name and be done with it, but it keeps happening, so there must be a fundamental reason why those people try to make the tool they want to share so unusable. Is it beneath them to actually give a code that runs?

Thank you.

Last example in date: "pst-osci" package

I even tried the .zip Manuel Luque gives on his website: it doesn't compile. Is there a lost compatibility because is work is from 2003 ? Or is there a special tool needed to use it ?

Thank you for your answer regarding "pst-osci"; it seems that examples are usable with LuaLaTeX:

there are many issues on compiling PSTricks with GhostScript, (according to Herbert) Lua is the recommended tool to process PSTricks.

LMT-PhD
  • 1,244
  • 2
    There are several 1000 LaTeX packages, and the documentation for these varies a lot: I don't think it's fair to say that in general such documentation does not contain workable examples. (The appropriate form will depend on the package in any case.) – Joseph Wright Oct 20 '22 at 10:13
  • 3
    While I can understand your thoughts I fear the question is not really on topic. But my two cents: writing code and writing documentation are two very different things. Not everybody is skilled at both. And there are very good documentations (surely not mine :-)) so I would not generalize. – campa Oct 20 '22 at 10:15
  • 4
    Look, you're getting software for free and you're complaining? You know the package author always have the option of not writing their package at all. – user202729 Oct 20 '22 at 10:15
  • 3
    (on a more positive note, you can help by making pull requests to the package repository to improve the documentation the way you like. The author might accept their pull request, and you don't require too much technical expertise to write documentation) – user202729 Oct 20 '22 at 10:16
  • @JosephWright, I do not mean that all documentations miss exemples, but that some do miss them when all of them should have one, making those too many. – LMT-PhD Oct 20 '22 at 11:07
  • @campa I am sure that those who start the documentation of a package have used it, I would bet even that in many cases the documentation is done by the package author. – LMT-PhD Oct 20 '22 at 11:09
  • @user202729 The problem is exactly that I am not getting software for free, I am just loosing my time, and I end up giving up because I cannot produce a single working exemple. And I would love to be able to contribute, but that won't happen since I can't make the damn thing work even once. – LMT-PhD Oct 20 '22 at 11:12
  • 1
    Some packages may only have been created for the author themselves before they were published on CTAN or somewhere else. They obviously knew how to use their own package. A manual was only an afterthough then. And an author may be too deep and knowledgable of their own package to write a good manual. (You never find every mistake you made in a text but another person takes one look and finds dozen without a problem.) Some authors expect common knowledge in basic (La)TeX which sometimes make it hard to follow the manual. – Qrrbrbirlbel Oct 20 '22 at 11:12
  • @Qrrbrbirlbel I think I understand what you say, but to me it is incompatible to produce a tool and the documentation with it to spread it for every one and then not do the first thing necessary to introduce it. – LMT-PhD Oct 20 '22 at 11:17
  • 1
    The documentations source is free available, at least on CTAN https://ctan.org/tex-archive/graphics/pstricks/contrib/pst-osci. The source shows for all examples how it could be done. – user187802 Oct 20 '22 at 11:34
  • 1
    It seems as if you were using pstricks with pdflatex the problem there is not lack of documentation but user error, not following the documentation and using a postscript-aware system (latex/dvips or more recently also luatatex, but not pdflatex) – David Carlisle Oct 20 '22 at 14:48
  • First, sometimes packages simply work for only very special, very particular circumstances and not generally. Second, even if the packages do work, producing GOOD documentation does take knowledge and effort. The documentation needn't start with an MWE; the documentation may even be completely lacking examples if it explains its usage in a more abstract and still readable and usable way. The authors have to be ABLE to produce good documentation. Finally, who pays the authors' efforts? Authors have to eat, sleep, exercise, and pay their bills, and all this costs. –  May 24 '23 at 02:59
  • I think there's not a handful of folks worldwide who have time, money, ability, and willingness to write good code with good documentation. (E.g., I could probably be able to educate myself and then write packages and their documentation, but I have no time and finances for this.) –  May 24 '23 at 03:01

1 Answers1

3

The last example from the documentation simply copied and then run it with lualatex

\documentclass[border=10mm]{standalone}
\usepackage{pst-osci}
\begin{document}

\psscalebox{0.5}{\Oscillo[amplitude1=3.5,phase1=90, amplitude2=3.5,period1=50,

    period2=50,phase2=0,Lissajous=true,damping1=0.01, Wave2=\RectangleB,damping2=0.01]}


\end{document}

enter image description here

user187802
  • 16,850