Re: Velocity Site - Almost ready to go

[Nathan Bubna <nb...@gmail.com>]

On 12/30/06, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
> Hi,
>
> after some amount of Maven wrestling, I have a new version of the
> intended Velocity Project site put at
>
> http://people.apache.org/~henning/site/

This is looking great!

> First some good and bad news:
>
> Good news: The Site builds now very smoothly with Maven 2 and the
>            Velocity Doxia Plugin.
>
> Bad news: It does not do so with Maven 2.0.4. It needs the current
>           2.0 SNAPSHOT.
>
> Good news: It is not our fault. It is Maven's fault (see
>            http://svn.apache.org/repos/asf/velocity/site/README.txt)
>
> Better news: There is a workaround for Maven 2.0.4. It is kludgy but
>              works.
>
> Even better news: For those of us that are maven impaired, I'm willing
>                   to build and deploy the site on demand. Maven 2.0.5
>                   should be out in January, afterwards there is no
>                   excuse. ;-)

Thanks!  :)

> I've read all of your suggestions and I agree with most of them. There
> will be a lot of shuffling around in the next few days / weeks, but
> the most important thing for us are IMHO:
>
> - We final sever our ties with Jakarta
> - We offer a welcome page, a download page and links to the projects
> - We have stable locations for release and development docs.
> - We have an easy and reproducable process to build the site
>
> Everything else can come later, can be reshuffled or rewritten.
>
> The one thing that I am missing from the site is the news page. I have
> some outline for a maven plugin that can read structured news items
> (some simple XML format) and provide
>
>  * A news page (all articles)
>  * A Doxia macro that displays the newest few items on the first page
>  * A RSS feed
>  * Aggregation of sub-feeds (think Engine Feed, Tools Feed aggregated
>    on the TLP site).
>
> That sounds complicated but the maven 2 plugins make this actually
> very simple and I intend to get this done before 2007. ;-)

Very cool.

> So what is in the site now (what has changed from the last version):
>
> - Project page and menu is gone. We can revive that later or just leave
>   it. If we make the engine a first class citizen, then we will have some
>   general engine docs in the wrapper site anyway, so why bother?
>
> - Moved Releases up, right after General
>
> - Added a "Reference library" link for often referenced documents.
>
> - Added a "Board reports" menu and the existing two board reports.
>
> - Filled most of the menu points with some content. The "Who we are"
>   and "Contact us" pages are generated from POM information.
>
>   If you want to change your information on the site, please update
>   the site POM (https://svn.apache.org/repos/asf/velocity/site/site/pom.xml)
>
> - "How it works" is basically a rip off from Jakarta. We should evaluate
>    these documents over time to see where they fit us and where not. Later.
>
> - The other "Apache Reference" links are unchanged. Feel free to do so.
>
> - Added "Site building" link which describes the process. This is the README
>   from the site converted to APT (APT is fun. Take a look at it. Sooo much
>   better than xdoc!)

But is APT as timeless as XML?  I'll take a look at it again, but i
worry that the format will not gain the longevity of XML.  And i'm
sure it will never gain the popularity and flexibility.  The great
benefit of xdoc was that it was just xml, for which there are many
tools and parsers and probably always will be.

Note: that the above is meant as loyal opposition.  i can't imagine
ever even thinking of vetoing any work anyone does on documentation.
on that matter, them that do the work not only make the decision, but
are also my personal heroes. :)

> Please take a look at the new site. If no objections come up, I will
> move this in sometime early next week (tuesday or wednesday). Until
> then I will have the news plugin ready and in place.

I'l try and update things with an announcement about tools 1.3-beta1
soon.  It's up on the servers, i just need to update download pages
and whatnot, then announce.  I meant to do it last week, but the
holidays won out.

> Afterwards I will work on the actual Engine docs. I expect some doc
> shuffling between the wrapper and the engine site and they will
> probably be in "construction site" mode for a while.
>
> Get ready for Velocity 1.5 in '07. ;-) (at what point will we make the
> vapor ware top 10 BTW?)

We haven't already??

>     Best regards
>          Henning
>
> --
> Henning P. Schmiedehausen  -- hps@intermeta.de | J2EE, Linux,
> 91054 Buckenhof, Germany   -- +49 9131 506540 | Apache person
> Open Source Consulting, Development, Design | Velocity - Turbine guy
>
>           "Save the cheerleader. Save the world."
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org

Re: Velocity Site - Almost ready to go

["Henning P. Schmiedehausen" <hp...@intermeta.de>]

"Nathan Bubna" <nb...@gmail.com> writes:

>> - Added "Site building" link which describes the process. This is the README
>>   from the site converted to APT (APT is fun. Take a look at it. Sooo much
>>   better than xdoc!)

>But is APT as timeless as XML?  I'll take a look at it again, but i
>worry that the format will not gain the longevity of XML.  And i'm
>sure it will never gain the popularity and flexibility.  The great
>benefit of xdoc was that it was just xml, for which there are many
>tools and parsers and probably always will be.

Well, yeah. However, there is one documentation format that is even
more timeless (IMHO) and easier than XML: Plain Text. And APT is
"almost plain text".

I was able to e.g. convert the board reports in five minutes to the
APT format, you can actually edit it well with a regular text editor
(emacs textmode works fine) and you can read it well in un-rendered
form, something that always hurt me with xdoc.

Getting used to "first column blank" for text is IMHO easy and worth
it.

Will it stand the test of time? Actually, I don't know. I'd say if we
want to ensure that, we should agree on a well established Wiki format
(maven supports e.g. Twiki) and use that and add a parser for that
format to Doxia (which is also quite simple if you got around the fact
that there is almost no documentation on Doxia (not even Javadocs) and
the current version of Maven has a bug with the <extensions> class
loading.

Ah, what Maven could benefit from good documentation. The potential is
*huge*.


>Note: that the above is meant as loyal opposition.  i can't imagine
>ever even thinking of vetoing any work anyone does on documentation.
>on that matter, them that do the work not only make the decision, but
>are also my personal heroes. :)

>> Please take a look at the new site. If no objections come up, I will
>> move this in sometime early next week (tuesday or wednesday). Until
>> then I will have the news plugin ready and in place.

>I'l try and update things with an announcement about tools 1.3-beta1
>soon.  It's up on the servers, i just need to update download pages
>and whatnot, then announce.  I meant to do it last week, but the
>holidays won out.

Yep, I saw that. Please try and see if you are able to find out on
yourself how to add a news-item to src/site/news.xml. I need to write
docs here, but the format is pretty straightforward. The actual
announcement text *is* APT format, that is why the Apt format is
linked in the "Reference Library" menu. ;-)

	Best regards
		Henning

-- 
Henning P. Schmiedehausen  -- hps@intermeta.de | J2EE, Linux,
91054 Buckenhof, Germany   -- +49 9131 506540 | Apache person
Open Source Consulting, Development, Design | Velocity - Turbine guy

          "Save the cheerleader. Save the world."

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org