Re: [PATCH] Massive restructuring into mandoc.h/libmandoc.a.

[Kristaps Dzonsons <kristaps@bsd.lv>]

> This is still not final feedback, i'm still trying to understand
> the details of what is happening, so here i'm only trying to
> describe my first impression what might need to be looked at.

Ingo,

Thanks for your input!  It seems, after a close read, that our goals are 
very similar.  I'm going to check in what I have and then shape it to 
the points below.  Don't worry---I can always roll back to the .10 tag, 
as all of these changes are structural.  Let's massage this in-tree.

> So, the overall structure is not bad, except for two messy points:
>
>   * main.h is a layering violation by its sheer existence;
>     parts belong in mdoc.h, man.h, term.h, html.h.
>   * mandoc.h is even worse;
>     registers belong in roff.h;
>     proper tbl.h and eqn.h would be cleaner;
>     the rest is lowest layer, together with libmandoc.h

I agree absolutely with the first.  It was originally created (by 
Joerg?) for a good reason: for the output engine prototypes.  Prior to 
that, if I recall, these prototypes were extern'd in main.c.

And yes, the registers will have to go from mandoc.h---I hadn't even 
noticed that (they were in the original mandoc.h).  I also agree with a 
proper tbl.h and eqn.h, but that can be done later.  Note the mdelim 
stuff will also go away once I do the right cueing (after all this mumbo 
jumbo).

>> Two things.  First off, see (2).  The parse() functions in both of
>> these headers were lies.  Second of all, and allowing for that, what
>> do we get by having both mdoc.h and man.h in terms of their type
>> definitions?  All this allows is for the two pairs, mdoc_XXXX.c and
>> man_XXXX.c, to have their own inclusions.  Big f. deal: everybody
>> else imports both anyway!  It's artificial to split them and,
>> although this isn't OpenBSD's problem, it puts an unnecessary burden
>> on distributing libmandoc.a (requiring mdoc.h and man.h hanger-ons)
>> for use by other utilities.
>
> Hm.  I guess here is my gripe.  I still don't see the point of
> clobbering everything into mandoc.h.  What's wrong with saying
>
> #include "man.h"
> #include "mdoc.h"
> #include "mandoc.h"
>
> in a program using libmandoc, if it really uses both parsers
> and the main reader?  It's neither better nor worse than just
>
> #include "mandoc.h"
>
> which includes everything; the difference is just keeping code
> organized by topic, keeping code for one topic in one file,
> which is easier to read and maintain.  And potentially, not
> having one header for everything also helps layering, doesn't it?

I'm still on the fence about this, but for the time being, I'll keep it 
as two (mdoc.h and man.h) and we can think about it some more.

My reasoning is simple: if all systems include mandoc/mdoc/man, why not 
just call it for what it is, and put them together?  If we run into 
layering problems, we can always split them out later.

> Well, i don't really worry about the Makefile, it is nice if
> it becomes shorter, but it won't come down to OpenBSD shortness
> any time soon.  ;-)

True.  But I bet, once you factor in <bsd.prog.mk>, mine's MUCH shorter. 
:) :)  The rest is the web-site.

Thanks again,

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv