From owner-freebsd-arch@FreeBSD.ORG Tue May 23 06:21:44 2006 Return-Path: X-Original-To: freebsd-arch@freebsd.org Delivered-To: freebsd-arch@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 8F5B316A427; Tue, 23 May 2006 06:21:44 +0000 (UTC) (envelope-from Alexander@Leidinger.net) Received: from www.ebusiness-leidinger.de (jojo.ms-net.de [84.16.236.246]) by mx1.FreeBSD.org (Postfix) with ESMTP id DFE7543D45; Tue, 23 May 2006 06:21:42 +0000 (GMT) (envelope-from Alexander@Leidinger.net) Received: from Andro-Beta.Leidinger.net (p54A5D288.dip.t-dialin.net [84.165.210.136]) (authenticated bits=0) by www.ebusiness-leidinger.de (8.13.4/8.13.1) with ESMTP id k4N69iTX017903; Tue, 23 May 2006 08:09:45 +0200 (CEST) (envelope-from Alexander@Leidinger.net) Received: from localhost (localhost [127.0.0.1]) by Andro-Beta.Leidinger.net (8.13.4/8.13.3) with ESMTP id k4N6LFgX037938; Tue, 23 May 2006 08:21:15 +0200 (CEST) (envelope-from Alexander@Leidinger.net) Received: from pslux.cec.eu.int (pslux.cec.eu.int [158.169.9.14]) by webmail.leidinger.net (Horde MIME library) with HTTP; Tue, 23 May 2006 08:21:15 +0200 Message-ID: <20060523082115.v4832wbvhcgccwwk@netchild.homeip.net> X-Priority: 3 (Normal) Date: Tue, 23 May 2006 08:21:15 +0200 From: Alexander Leidinger To: gnn@freebsd.org References: <200605181516.15541.hm@kts.org> <39318.1147960050@critter.freebsd.dk> <20060519143116.9iuvd81es0g0owkc@netchild.homeip.net> <20060522101825.adfzv59y1eogwocs@netchild.homeip.net> In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8; DelSp="Yes"; format="flowed" Content-Disposition: inline Content-Transfer-Encoding: quoted-printable User-Agent: Internet Messaging Program (IMP) H3 (4.1) / FreeBSD-4.11 X-Virus-Scanned: by amavisd-new X-Mailman-Approved-At: Tue, 23 May 2006 12:03:39 +0000 Cc: Poul-Henning Kamp , hellmuth.michaelis@t-online.de, Julian Elischer , freebsd-arch@freebsd.org Subject: Re: doxygen target (was: Re: cvs commit: src Makefile.inc1 ObsoleteFiles.inc src/etc/defaults rc.conf src/etc/mtree BSD.usr.dist src/etc/rc.d Makefile isdnd pcvt syscons src/release/picobsd/build picobsd src/share/man/man4 Makefile atkbd.4 kbdmux.4 pcvt.4 splash.4 vkbd.4 ...) X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 23 May 2006 06:21:45 -0000 Quoting gnn@freebsd.org (from Mon, 22 May 2006 16:50:11 -0700): > At Mon, 22 May 2006 10:18:25 +0200, > Alexander Leidinger wrote: >> Regarding the make target, do you think about "cd /usr/src; make >> doxygen" or about "cd /usr/src/; make doxygen"? > > Yes :-) It hsould be possible to be as specific or non-specific as > possible. There can then be nightly builds of the docs, much like > running global nightly to get cross references like I put up on > codespelunking.org I try to come up with the /usr/src doxygen target first. >> The targets in the .tar.bz2 generate a HTML version too. Currently >> the HTML version is around 300 MB, and it only covers a small part >> of the kernel. Shall the HTML version also be generated (not >> available online)? What about the destination, where do you want the >> HTML version and/or the PDF version (needs pdflatex as a build tool) >> to be placed (I can't come up with a good destination)? The HTML >> version is generated by doxygen directly, the PDF needs to be >> generated from the latex version, so in case of the PDF version it >> would make sense to have a "doxygen" and "doxygeninstall" target, >> but not for the HTML version (except you want to generate everything >> in OBJDIR and then do a copy to the destination). >> >> Yes, I'm asking bikeshed questions... but only because I can't think >> of a good answer myself ATM. > > My preference, and I'm not a Doxygen guru, is that we generate HTML > from /usr/src into a /usr/doc directory, which is like /usr/obj, then Sounds fine to me. One directory per subsystem if we go the split-up way. > some folks can serve /usr/doc on the net. Sub directory builds should > make sub-directory doc directories. I.e. /usr/src/sys/netinet/doc. I > think that /usr/src/sys is already a special root which gets a doc > directory, and I think that's fine. For now I want to emphasize > simplicity. I'm not sure the subdirectory builds are that simple to implement in a =20 generic fashion (I have to play around with some ideas here...). =20 Adding a target by hand to each interesting subdirectory is easy. > THe other thing we need guidance on is, if people want to, how to most > easily add clear annotations to soiurce that make Doxygen happy. A > one page cheat sheet would go a long way towards making this usable by > people who don't like to write documentation :-) I think http://www.stack.nl/~dimitri/doxygen/docblocks.html provides a =20 good start (until someone writes doxygen_style(9) :-) ). A FAQ is available at http://www.stack.nl/~dimitri/doxygen/faq.html =20 and http://www.stack.nl/~dimitri/doxygen/commands.html contains a list =20 of all doxygen recognized documentation-commands. Bye, Alexander. --=20 Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR you have to pick it up between Germany/Saarland and Luxembourg/Capellen http://www.Leidinger.net Alexander @ Leidinger.net: PGP ID =3D B0063FE7 http://www.FreeBSD.org netchild @ FreeBSD.org : PGP ID =3D 72077137