[TUHS] man Macro Package and pdfmark

[Bakul Shah]

On Mon, 17 Feb 2020 16:17:18 -0800 Jon Steinhart <jon at fourwinds.com> wrote:
> Richard Salz writes:
> >
> > > 'The problem is that the ecosystem has been fragmented by people doing
> > their "documentation" in their preferred formats instead of in a common
> > (man) format.
> >
> > Damn those unauthorized developers.  How dare they write code that doesn't
> > meet standards.
> >
> > Get off my lawn.
>
> The relevant TUHS part of it that maybe some folks here can speak to is how
> did UNIX remain so cohesive for so long?  How were decisions made?  Of course,
> this started to fall apart with System III and such as things got more clunky.

Agree. I don't mind additional documentation but a man page is
strongly preferred.

> Noel Chiappa writes:
> > I am _sooo_ tempted to say 'What do you think source is for?' :-)
>
> I think that this is part of the problem, have you looked at the source for
> any modern package?  It's pretty impenetrable.  I see a lot of overly complex,
> poorly written code with no documentation.  That makes it really difficult for
> someone to extend or otherwise modify it.  It's probably easier to create a
> new universe than understand an existing one.

There is just so much more code now and the S/N ratio is
definitely worse but there is more good stuff as well.

My problems with using the source as documentation:
a) there is usually no or insufficient documentation about
   even what it is implementing let alone *how* it should be
   used,
b) you don't know if some behavior is an accident of the way
   the code behaves or actually part of some required (but
   unwritten) specification.
c) even if there some function header comments often there is no
   top level comment tying together eveyrthing. 
d) harder to see missing functionality.
e) impossible to grok large programs.