You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doxia-dev@maven.apache.org by Vincent Siveton <vi...@gmail.com> on 2007/07/29 23:06:50 UTC
Design thoughts
Hi,
As you know, Doxia modules need to be more consistents. Dennis pointed
the EOL problem today.
I recently added several markup interfaces. I see 2 types of markup
languages handles by Doxia: text (like APT) and xml (like xdoc). I
propose to encapsulate these things with the following interfaces:
Markup (core)
|_ TextMarkup (core)
|_ AptMarkup (module)
|_ XmlMarkup (core)
|_ XdocMarkup (module)
In a second step, I propose to create abstract TextSink and XmlSink to
encapsulate writer. With this, we will remove inconsistencies in the
output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
Thoughts?
Vincent
Re: Design thoughts
Posted by Dennis Lundberg <de...@apache.org>.
Vincent Siveton wrote:
> Hi,
>
> As you know, Doxia modules need to be more consistents. Dennis pointed
> the EOL problem today.
>
> I recently added several markup interfaces. I see 2 types of markup
> languages handles by Doxia: text (like APT) and xml (like xdoc). I
> propose to encapsulate these things with the following interfaces:
> Markup (core)
> |_ TextMarkup (core)
> |_ AptMarkup (module)
> |_ XmlMarkup (core)
> |_ XdocMarkup (module)
That sounds like a good separation of them.
> In a second step, I propose to create abstract TextSink and XmlSink to
> encapsulate writer. With this, we will remove inconsistencies in the
> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
+1
>
> Thoughts?
>
> Vincent
--
Dennis Lundberg
Re: Design thoughts
Posted by Jason van Zyl <ja...@maven.org>.
On 30 Jul 07, at 12:41 PM 30 Jul 07, Vincent Siveton wrote:
> Hi Jason,
>
> 2007/7/30, Jason van Zyl <ja...@maven.org>:
>>
>> On 30 Jul 07, at 5:06 AM 30 Jul 07, Dennis Lundberg wrote:
>>
>>> Brett Porter wrote:
>>>> I haven't been keeping track unfortunately, so maybe I'm missing a
>>>> piece of the puzzle.
>>>> How does a 'Markup' relate to a 'Parser', which is what I thought
>>>> the terminology was for this?
>>>
>>> The Markup classes contain utility constants/methods for handling
>>> markup. Constants like these would go into XmlMarkup
>>> String START_MARKUP = "<";
>>> String END_MARKUP = ">";
>>>
>>
>> This is still something that happens in the parser yes? You're
>> parsing the markup and these interfaces would be used during the
>> parsing of the incoming stream, yes?
>
> These markups interfaces are only used to define constants which are
> used by parser and module sinks (actually apt, xdoc, xhtml)
>
Then why don't you call them XXXParser?
>>> General stuff that
>>>
>>>> The only caution I urge is that anything that changes doxia-sink-
>>>> api might limit the ability to use it across different versions of
>>>> Maven. Other than that, I think it'd be good to decide the target
>>>> public API, write it up and then refactor towards it... it might
>>>> be easier to understand holistically.
>>>
>>> Yup, we need to be careful not to move too much to the API, but I
>>> think Vincent is only talking about the really general stuff here.
>>
>> You can't make any binary incompatible changes at all at this point
>> even though doxia says it's in alpha everything is bound to it.
>
> AFAIK we don't plan to change the Sink API at all.
> The only changes (for beta-1) could be to add few methods like
> keywords() (DOXIA-129) or to handle styles.
Additions are fine.
>
> Cheers,
>
> Vincent
>
>>>
>>>> Thanks guys!
>>>> Cheers,
>>>> Brett
>>>> On 30/07/2007, at 7:06 AM, Vincent Siveton wrote:
>>>>> Hi,
>>>>>
>>>>> As you know, Doxia modules need to be more consistents. Dennis
>>>>> pointed
>>>>> the EOL problem today.
>>>>>
>>>>> I recently added several markup interfaces. I see 2 types of
>>>>> markup
>>>>> languages handles by Doxia: text (like APT) and xml (like xdoc). I
>>>>> propose to encapsulate these things with the following interfaces:
>>>>> Markup (core)
>>>>> |_ TextMarkup (core)
>>>>> |_ AptMarkup (module)
>>>>> |_ XmlMarkup (core)
>>>>> |_ XdocMarkup (module)
>>>>>
>>>>> In a second step, I propose to create abstract TextSink and
>>>>> XmlSink to
>>>>> encapsulate writer. With this, we will remove inconsistencies
>>>>> in the
>>>>> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
>>>>>
>>>>> Thoughts?
>>>>>
>>>>> Vincent
>>>
>>>
>>> --
>>> Dennis Lundberg
>>
>> Thanks,
>>
>> Jason
>>
>> ----------------------------------------------------------
>> Jason van Zyl
>> Founder and PMC Chair, Apache Maven
>> jason at sonatype dot com
>> ----------------------------------------------------------
>>
>>
>>
>>
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
Re: Design thoughts
Posted by Vincent Siveton <vi...@gmail.com>.
Hi Jason,
2007/7/30, Jason van Zyl <ja...@maven.org>:
>
> On 30 Jul 07, at 5:06 AM 30 Jul 07, Dennis Lundberg wrote:
>
> > Brett Porter wrote:
> >> I haven't been keeping track unfortunately, so maybe I'm missing a
> >> piece of the puzzle.
> >> How does a 'Markup' relate to a 'Parser', which is what I thought
> >> the terminology was for this?
> >
> > The Markup classes contain utility constants/methods for handling
> > markup. Constants like these would go into XmlMarkup
> > String START_MARKUP = "<";
> > String END_MARKUP = ">";
> >
>
> This is still something that happens in the parser yes? You're
> parsing the markup and these interfaces would be used during the
> parsing of the incoming stream, yes?
These markups interfaces are only used to define constants which are
used by parser and module sinks (actually apt, xdoc, xhtml)
> > General stuff that
> >
> >> The only caution I urge is that anything that changes doxia-sink-
> >> api might limit the ability to use it across different versions of
> >> Maven. Other than that, I think it'd be good to decide the target
> >> public API, write it up and then refactor towards it... it might
> >> be easier to understand holistically.
> >
> > Yup, we need to be careful not to move too much to the API, but I
> > think Vincent is only talking about the really general stuff here.
>
> You can't make any binary incompatible changes at all at this point
> even though doxia says it's in alpha everything is bound to it.
AFAIK we don't plan to change the Sink API at all.
The only changes (for beta-1) could be to add few methods like
keywords() (DOXIA-129) or to handle styles.
Cheers,
Vincent
> >
> >> Thanks guys!
> >> Cheers,
> >> Brett
> >> On 30/07/2007, at 7:06 AM, Vincent Siveton wrote:
> >>> Hi,
> >>>
> >>> As you know, Doxia modules need to be more consistents. Dennis
> >>> pointed
> >>> the EOL problem today.
> >>>
> >>> I recently added several markup interfaces. I see 2 types of markup
> >>> languages handles by Doxia: text (like APT) and xml (like xdoc). I
> >>> propose to encapsulate these things with the following interfaces:
> >>> Markup (core)
> >>> |_ TextMarkup (core)
> >>> |_ AptMarkup (module)
> >>> |_ XmlMarkup (core)
> >>> |_ XdocMarkup (module)
> >>>
> >>> In a second step, I propose to create abstract TextSink and
> >>> XmlSink to
> >>> encapsulate writer. With this, we will remove inconsistencies in the
> >>> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
> >>>
> >>> Thoughts?
> >>>
> >>> Vincent
> >
> >
> > --
> > Dennis Lundberg
>
> Thanks,
>
> Jason
>
> ----------------------------------------------------------
> Jason van Zyl
> Founder and PMC Chair, Apache Maven
> jason at sonatype dot com
> ----------------------------------------------------------
>
>
>
>
Re: Design thoughts
Posted by Jason van Zyl <ja...@maven.org>.
On 30 Jul 07, at 5:06 AM 30 Jul 07, Dennis Lundberg wrote:
> Brett Porter wrote:
>> I haven't been keeping track unfortunately, so maybe I'm missing a
>> piece of the puzzle.
>> How does a 'Markup' relate to a 'Parser', which is what I thought
>> the terminology was for this?
>
> The Markup classes contain utility constants/methods for handling
> markup. Constants like these would go into XmlMarkup
> String START_MARKUP = "<";
> String END_MARKUP = ">";
>
This is still something that happens in the parser yes? You're
parsing the markup and these interfaces would be used during the
parsing of the incoming stream, yes?
> General stuff that
>
>> The only caution I urge is that anything that changes doxia-sink-
>> api might limit the ability to use it across different versions of
>> Maven. Other than that, I think it'd be good to decide the target
>> public API, write it up and then refactor towards it... it might
>> be easier to understand holistically.
>
> Yup, we need to be careful not to move too much to the API, but I
> think Vincent is only talking about the really general stuff here.
You can't make any binary incompatible changes at all at this point
even though doxia says it's in alpha everything is bound to it.
>
>> Thanks guys!
>> Cheers,
>> Brett
>> On 30/07/2007, at 7:06 AM, Vincent Siveton wrote:
>>> Hi,
>>>
>>> As you know, Doxia modules need to be more consistents. Dennis
>>> pointed
>>> the EOL problem today.
>>>
>>> I recently added several markup interfaces. I see 2 types of markup
>>> languages handles by Doxia: text (like APT) and xml (like xdoc). I
>>> propose to encapsulate these things with the following interfaces:
>>> Markup (core)
>>> |_ TextMarkup (core)
>>> |_ AptMarkup (module)
>>> |_ XmlMarkup (core)
>>> |_ XdocMarkup (module)
>>>
>>> In a second step, I propose to create abstract TextSink and
>>> XmlSink to
>>> encapsulate writer. With this, we will remove inconsistencies in the
>>> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
>>>
>>> Thoughts?
>>>
>>> Vincent
>
>
> --
> Dennis Lundberg
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
Re: Design thoughts
Posted by Vincent Siveton <vi...@gmail.com>.
Hi,
2007/7/30, Dennis Lundberg <de...@apache.org>:
> Brett Porter wrote:
> > I haven't been keeping track unfortunately, so maybe I'm missing a piece
> > of the puzzle.
> >
> > How does a 'Markup' relate to a 'Parser', which is what I thought the
> > terminology was for this?
>
> The Markup classes contain utility constants/methods for handling
> markup. Constants like these would go into XmlMarkup
> String START_MARKUP = "<";
> String END_MARKUP = ">";
>
> General stuff that
used only in parser and module sink.
>
> > The only caution I urge is that anything that changes doxia-sink-api
> > might limit the ability to use it across different versions of Maven.
> > Other than that, I think it'd be good to decide the target public API,
> > write it up and then refactor towards it... it might be easier to
> > understand holistically.
>
> Yup, we need to be careful not to move too much to the API, but I think
> Vincent is only talking about the really general stuff here.
Exactly.
Cheers,
Vincent
> > Thanks guys!
> >
> > Cheers,
> > Brett
> >
> > On 30/07/2007, at 7:06 AM, Vincent Siveton wrote:
> >
> >> Hi,
> >>
> >> As you know, Doxia modules need to be more consistents. Dennis pointed
> >> the EOL problem today.
> >>
> >> I recently added several markup interfaces. I see 2 types of markup
> >> languages handles by Doxia: text (like APT) and xml (like xdoc). I
> >> propose to encapsulate these things with the following interfaces:
> >> Markup (core)
> >> |_ TextMarkup (core)
> >> |_ AptMarkup (module)
> >> |_ XmlMarkup (core)
> >> |_ XdocMarkup (module)
> >>
> >> In a second step, I propose to create abstract TextSink and XmlSink to
> >> encapsulate writer. With this, we will remove inconsistencies in the
> >> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
> >>
> >> Thoughts?
> >>
> >> Vincent
>
>
> --
> Dennis Lundberg
>
Re: Design thoughts
Posted by Dennis Lundberg <de...@apache.org>.
Brett Porter wrote:
> I haven't been keeping track unfortunately, so maybe I'm missing a piece
> of the puzzle.
>
> How does a 'Markup' relate to a 'Parser', which is what I thought the
> terminology was for this?
The Markup classes contain utility constants/methods for handling
markup. Constants like these would go into XmlMarkup
String START_MARKUP = "<";
String END_MARKUP = ">";
General stuff that
> The only caution I urge is that anything that changes doxia-sink-api
> might limit the ability to use it across different versions of Maven.
> Other than that, I think it'd be good to decide the target public API,
> write it up and then refactor towards it... it might be easier to
> understand holistically.
Yup, we need to be careful not to move too much to the API, but I think
Vincent is only talking about the really general stuff here.
> Thanks guys!
>
> Cheers,
> Brett
>
> On 30/07/2007, at 7:06 AM, Vincent Siveton wrote:
>
>> Hi,
>>
>> As you know, Doxia modules need to be more consistents. Dennis pointed
>> the EOL problem today.
>>
>> I recently added several markup interfaces. I see 2 types of markup
>> languages handles by Doxia: text (like APT) and xml (like xdoc). I
>> propose to encapsulate these things with the following interfaces:
>> Markup (core)
>> |_ TextMarkup (core)
>> |_ AptMarkup (module)
>> |_ XmlMarkup (core)
>> |_ XdocMarkup (module)
>>
>> In a second step, I propose to create abstract TextSink and XmlSink to
>> encapsulate writer. With this, we will remove inconsistencies in the
>> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
>>
>> Thoughts?
>>
>> Vincent
--
Dennis Lundberg
Re: Design thoughts
Posted by Brett Porter <br...@apache.org>.
I haven't been keeping track unfortunately, so maybe I'm missing a
piece of the puzzle.
How does a 'Markup' relate to a 'Parser', which is what I thought the
terminology was for this?
The only caution I urge is that anything that changes doxia-sink-api
might limit the ability to use it across different versions of Maven.
Other than that, I think it'd be good to decide the target public
API, write it up and then refactor towards it... it might be easier
to understand holistically.
Thanks guys!
Cheers,
Brett
On 30/07/2007, at 7:06 AM, Vincent Siveton wrote:
> Hi,
>
> As you know, Doxia modules need to be more consistents. Dennis pointed
> the EOL problem today.
>
> I recently added several markup interfaces. I see 2 types of markup
> languages handles by Doxia: text (like APT) and xml (like xdoc). I
> propose to encapsulate these things with the following interfaces:
> Markup (core)
> |_ TextMarkup (core)
> |_ AptMarkup (module)
> |_ XmlMarkup (core)
> |_ XdocMarkup (module)
>
> In a second step, I propose to create abstract TextSink and XmlSink to
> encapsulate writer. With this, we will remove inconsistencies in the
> output like LineBreaker (docbook, xdoc) vs PrintWriter (xhtml).
>
> Thoughts?
>
> Vincent