[CALL FOR REVIEW] doc and www converted to XML

[Simon L. B. Nielsen]

On 21 Aug 2012, at 22:18, Gabor Kovesdan <gabor at FreeBSD.org> wrote:

> Em 21-08-2012 21:54, Simon L. B. Nielsen escreveu:
>> 
>> On 20 Aug 2012, at 17:48, Gabor Kovesdan <gabor at FreeBSD.org> wrote:
>> 
>>> Dear Folks,
>>> 
>>> I'm glad to announce that the first milestone of the XML migration is
>>> available for review in the projects/sgml2xml branch. To check it out,
>>> run the following:
>>> 
>>> svn co http://svn.freebsd.org/doc/projects/sgml2xml sgml2xml
>>> 
>>> The build process - from the end user perspective - works in the same
>>> way. In short, use make all at the proper place, to build only web, run
>>> make all WEB_ONLY=yes in the htdocs dir, etc. Then use make install with
>>> DESTDIR defined to install files to the proper place.
>> 
>> We really should fix this (the magic of en/htdocs building other languages too etc; DESTDIR not meaning what it does in base etc.), but that can be done later.
> 
> Agreed. Besides, we have DOCDIR, WEBGRP, DOCGRP. They should just be
> DESTDIR and DOCGRP. But I think it comes from the times when doc and www
> were separated more physically.

Well, to a degree - it shouldn't be DESTDIR IMO, as DESTDIR in src is by default, and BINDIR etc. sets where things live relative to that... as in, paths are basically:

${DESTDIR}${BINDIR}/ls (where BINDIR is /bin)

and so on.  So IMO, we should use something other than DESTDIR to say where things live relative to the "root"... anyway, it wasn't that I wanted to really disuss this now as I don't want to sidetrack the XML work, I was just reminded that our build system really is a mess :-) (I tried to rewrite it from scratch once... it's not trivial :-) ).

>> I looked at a random page, and the identation for the header is a bit funny. Is that just an artifact of an automatic conversion or? Example: http://svnweb.freebsd.org/doc/projects/sgml2xml/en_US.ISO8859-1/htdocs/logo.sgml?revision=39396&view=markup
> 
> Yes, it was a scripted conversion and because of the indentation of
> files is not consistent, I couldn't do it in a way that would match all
> files.

OK, then I think that should just be cleaned up later as we go.

>> If you are going to change it, could you please change it to use svn and with a REPO path we can set from the web build wrapper? I would REALLY like if we could get the web build fixed to never try to get data from the internet.
> 
> I don't think it is (a) entirely possible and I'm not sure if it's (b)
> practical.
> (a) You cannot easily build INDEX as part of the doc build and there are

Eh, you don't need to. That's why we have an override to point the build at the right INDEX file. We (as in, www.FreeBSD.org) don't fetch it now.

> some pages that already depend on remote resources. I remember that
> something fetches some .rdf files and the GNOME newsflash used to pull
> in some official GNOME news. This part stopped to work so I commented it

Yes, I strongly disagree that we should have that due to the problems whenever upstream doesn't work.

> out.

OK, good :-).

> (b) I think depending on having a local svn mirror of ports is worse
> than just fetching a simple file. Ok, you could set the repo path to the
> remote repo but that needs setup and fetching from http just works out
> of the box.

> What do others think?

I'm fine if you do it for people who want it, but please make an override which can be used for www.FreeBSD.org etc.  Also, there is nothing which says the the mirror has to be local. If you just make it a repo path, it will be able to work via HTTP for normal users directly from an svn mirror too.

>> Do that mean that the current build dependencies are unchanged?
> 
> Yes. We went to DocBook 4.2 but it was already a dependency. And I could
> build everything on freefall.

Great, that was mostly as we of course need to have any new dependency installed on all the relevant FreeBSD.org servers.

-- 
Simon L. B. Nielsen