Re: mdocml: Renamed mandoc.c to libmandoc.c.

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

kristaps@mdocml.bsd.lv wrote on Mon, Jul 05, 2010 at 04:00:56PM -0400:

> Log Message:
> -----------
> Renamed mandoc.c to libmandoc.c.  This is in the efforts of getting a
> cleaner namespace for functions across the entire system (mandoc.h:
> getting parsed-string values, or declarations necessary for the AST
> data), and compiler functions (libmandoc.h: back-end functions and
> declarations).

I dislike this change.
I think the attempt to get a cleaner namespace this way is futile.

The whole concept of x.h vs. libx.h doesn't work out, there is
no real separation.  As far as i understand, the idea is to have
the pure AST parts in x.h, such that x.h is self-contained
except for requiring mandoc.h, while libx.h is supposed to be
the interface to one specific X parser which happens to be
using x.h, while x.h does not depend on the specific parser
interface defined by libx.h.

But this is already busted, because lots of functions from man.h
use the forward declaration of struct man from libman.h,
and lots of functions from mdoc.h use the forward declaration
of struct mdoc from libmdoc.h, so the AST cannot exist without
the one specific parser we have.  I don't say that is a problem,
because i guess nobody will ever try to write an alternative parser
using man.h or mdoc.h.  My point is just that the separation
of x.h and libx.h is mere fiction.  We could as well put
x.h and libx.h into one header (of course, don't, that would
just cause useless churn).

That said, i see no point in extending this failed concept to
mandoc.h and libmandoc.h.  I didn't speak up yet because i don't
feel that strongly about which function is defined in which header
and implemented in which .c-file, so i was mostly happy with
what we have.

But i do care about CVS history, so i think renaming mandoc.c
is a really bad idea.  We lose history for no reason.

I think this change ought to be undone.  That is, undone on the
RCS level, not just reverted by renaming the file once more.

Yours,
  Ingo


P.S.
Btw., while trying to figure out how headers and .c-files are
related, i found a few weirdnesses:

 * libmdoc.h declares mdoc_isescape and mdoc_atotime
   which are neither defined nor used
 * man.c: man_pmacro lacks static on its definition
 * man.c implements man.h without explicitely including it;
   it is only included via libman.h
 * man_macro.c: blk_close, blk_exp, blk_exp, in_line_eoln
   lack static on their definitions
 * mdoc.c: mdoc_node_free and mdoc_pmacro
   lack static on their definitions
 * mdoc.c implements mdoc.h without explicitely including it
   it is only included via libmdoc.h

These are probably easily fixed, while the following are not:

 * roff.h forward-declares struct roff
   which is not declared in any header at all,
   but only in roff.c, using more local roff.c declarations.
   That is, the roff.h interface is *not* independent of the
   particular roff.c implementation.
 * The forward declaration of struct man and struct mdoc
   in main.h is ugly, too, because effectively, that makes
   main.h depend on libman.h and libmdoc.h, thus also on
   man.h, mdoc.h and mandoc.h.  Now, main.h is used all over
   the place (html.c, man_html.c, man_term.c, mdoc_html.c,
   mdoc_term.c, term.c, term_ascii.c, term_ps.c, tree.c),
   which means that all these files depend on the full AST
   structure and BOTH parsers - yes, even the man frontends
   are not cleanly separated from the mdoc parser and vice
   versa.
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv