Dear fink developers,
As some of you know, we have a pretty slick system for generating our
web pages, using xml source which is processed into php files.
The same xml source can be processed into more "monolithic" html files,
which are distributed these days with the binary installer. Also, some
parts of the source are processed into txt files, and become part of
fink's source distribution.
The latter two steps are not fully automated, and I'd like to propose a
reorganization of how we work with these files on CVS, in order to
automate things completely.
The first part of the new organization would be adding two lines to
CVSROOT/modules, namely:
website -a !web/xml web
xml web/xml &fink &website &scripts
This defines two new CVS modules that can be checked out, but without
actually making new directories within CVS: they are virtual modules.
The first one, "website", is the same as the current "web" module,
except that it leaves out the xml subdirectory of the web module.
(This would be used on the actual fink website in my scheme: we don't
actually need the xml files to be present on the web site.)
The second new module "xml" would contain all of the xml source, as
well as three subdirectories "fink", "website", and "scripts" where
the processed source would be installed. Now the beauty of these
virtual modules is that those three subdirectories are themselves cvs
modules, which could be checked out independently, so this strategy
deposits the output from the xml processing directly where it is
needed.
So, after adding these two new modules, I would need to change the Makefiles
(diffs below). I couldn't find a way to make the Makefiles work in both
the old and the new setup, so if folks agree to this change, one implication
is that everyone who works on the documentation will have to abandon their
current checkout of "web", and instead do a new checkout of "xml" to
do their documentation work.
I also needed an addition to the .dtd, because there is one place where
the URL that we want to pass is different when you install the monolithic
html in "scripts", as compared with what you install in "website". So
I created the "varlink" template which requires two URL's to be supplied,
one used for the html and one used for the website.
Max and I briefly discussed this idea a few months ago after the 0.5.2
release, and he suggested that I should bring it to the list, in detail,
before implementation. Putting out the 0.5.3 release motivated me again
to work on this, so that in future releases we don't have to fix up the
documentation "by hand."
I would appreciate any comments or feedback about this. Diffs attached
below (for Makefile.common, the .dtd, the .xsl's, and the one .xml which
requires the new "varlink" template.
-- Dave
--- Makefile.common.orig Sun Jun 22 20:22:59 2003
+++ Makefile.common Sat Jun 28 18:56:02 2003
@@ -12,7 +12,7 @@
PROCESS_WEBSITE = $(basedir)/postprocess.pl
PROCESS_HTML = sed -e 's,$$Id,$$Fink,g'
-PROCESS_TEXT = $(basedir)/textify.pl
+PROCESS_TEXT = /usr/bin/perl $(basedir)/textify.pl
# selectors
@@ -20,13 +20,18 @@
install_files = $(TARGET)
#install_files = $(filter %.php,$(TARGET))
+## NOTE: need to remove the .html files from the web installation, in CVS
+
ifdef WANT_HTML
all_targets += $(patsubst %.xml,%.html,$(SOURCE))
-install_files += $(patsubst %.xml,%.html,$(SOURCE))
+#install_files += $(patsubst %.xml,%.html,$(SOURCE))
+install_html = $(patsubst %.xml,%.html,$(SOURCE))
endif
ifdef WANT_TEXT
all_targets += $(patsubst %.xml,%.txt,$(SOURCE))
+install_txt = $(patsubst %.xml,%.txt,$(SOURCE))
+install_txt += $(patsubst %.xml,%.html,$(SOURCE))
endif
# basics
@@ -73,9 +78,16 @@
install: $(install_files)
ifdef DESTDIR
- cp $(install_files) $(basedir)/../$(DESTDIR)/
+ cp $(install_files) $(basedir)/web/$(DESTDIR)/
else
@echo "DESTDIR not defined, can't install"
endif
+ifdef WANT_HTML
+ cp $(install_html) $(basedir)/scripts/installer/dmg/$(DESTDIR)/
+endif
+ifdef WANT_TEXT
+ cp $(install_txt) $(basedir)/fink/
+endif
+
# eof
--- doc/doc.xml-orig Sun Jun 22 20:23:00 2003
+++ doc/doc.xml Sat Jun 28 20:15:11 2003
@@ -20,12 +20,12 @@
The current user documentation for Fink:
</p>
<ul>
-<li><link url="users-guide/index.php">Fink User's Guide</link> -
+<li><varlink url="users-guide/index.php" varurl="users-guide/uguide.html">Fink User's
Guide</varlink> -
this covers installing Fink itself, installing packages, and upgrading
to a new Fink release. It contains instructions for both the source
and the binary release.
<em>Work in Progress!</em></li>
-<li><link url="x11/index.php">Running X11 on Darwin and Mac OS X</link> -
+<li><varlink url="x11/index.php" varurl="x11/x11.html">Running X11 on Darwin and Mac
OS X</varlink> -
covers concepts, installation and launching (also intended for Darwin
and Mac OS X users in general)</li>
</ul>
@@ -35,13 +35,13 @@
no longer maintained:
</p>
<ul>
-<li><link url="bundled/install.php">Installation and Upgrading</link> - how
+<li><varlink url="bundled/install.php" varurl="bundled/install.html">Installation and
Upgrading</varlink> - how
to install Fink or upgrade to a new version</li>
-<li><link url="bundled/usage.php">Usage</link> - how to use Fink
+<li><varlink url="bundled/usage.php" varurl="bundled/usage.html">Usage</varlink> -
how to use Fink
and the installed software</li>
-<li><link url="bundled/readme.php">Fink ReadMe</link> - the ReadMe for the
+<li><varlink url="bundled/readme.php" varurl="bundled/readme.html">Fink
ReadMe</varlink> - the ReadMe for the
source distribution</li>
-<li><link url="cvsaccess/index.php">CVS Access</link> - how to access the
+<li><varlink url="cvsaccess/index.php" varurl="cvsaccess/cvs.html">CVS
Access</varlink> - how to access the
Fink CVS repository to get the latest source packages between
releases</li>
</ul>
@@ -56,9 +56,9 @@
url="http://conferences.oreillynet.com/macosx2002/";
>O'Reilly Mac OS X Conference</link> (also available as a
<link
url="http://conferences.oreillynet.com/presentations/macosx02/morrison_david.ppt";>PowerPoint
file</link>) </li>
-<li><link url="porting/index.php">Porting Tips</link> - notes for porting
+<li><varlink url="porting/index.php" varurl="porting/porting.html">Porting
Tips</varlink> - notes for porting
Unix applications to Darwin</li>
-<li><link url="packaging/index.php">Packaging Manual</link> - how to create and
+<li><varlink url="packaging/index.php" varurl="packaging/packaging.html">Packaging
Manual</varlink> - how to create and
maintain Fink packages</li>
</ul>
--- finkdoc.dtd-orig Sun Jun 22 20:22:59 2003
+++ finkdoc.dtd Sat Jun 28 20:04:14 2003
@@ -1,5 +1,5 @@
<!ENTITY % block "codeblock | ol | p | ul" >
-<!ENTITY % inline "#PCDATA | code | em | filename | link | tt | quote | xref" >
+<!ENTITY % inline "#PCDATA | code | em | filename | link | varlink | tt | quote |
xref" >
<!ENTITY fink_version "0.5.2" >
@@ -41,6 +41,12 @@
<!-- Links -->
<!ELEMENT link ( #PCDATA ) >
<!ATTLIST link url CDATA #REQUIRED >
+
+<!-- VarLinks -->
+<!ELEMENT varlink ( #PCDATA ) >
+<!ATTLIST varlink url CDATA #REQUIRED >
+<!ATTLIST varlink varurl CDATA #REQUIRED >
+
<!ELEMENT xref ( #PCDATA ) >
<!ATTLIST xref chapter IDREF #IMPLIED >
--- finkdoc-html.xsl-orig Sun Jun 22 20:22:59 2003
+++ finkdoc-html.xsl Sat Jun 28 20:05:30 2003
@@ -193,6 +193,10 @@
<a href="[EMAIL PROTECTED]"><xsl:apply-templates/></a>
</xsl:template>
+<xsl:template match="varlink">
+<a href="[EMAIL PROTECTED]"><xsl:apply-templates/></a>
+</xsl:template>
+
<xsl:template match="xref">
<a><xsl:attribute name="href">#<xsl:choose><xsl:when
test="boolean(@chapter)"><xsl:value-of select="@chapter"
/></xsl:when><xsl:otherwise><xsl:for-each select="ancestor::chapter |
ancestor::article"><xsl:value-of
select="@filename"/></xsl:for-each></xsl:otherwise></xsl:choose><xsl:if
test="boolean(@section)">.<xsl:value-of select="@section" /></xsl:if></xsl:attribute>
<xsl:apply-templates/></a>
--- finkdoc-text.xsl-orig Sun Jun 22 20:22:59 2003
+++ finkdoc-text.xsl Sat Jun 28 20:06:42 2003
@@ -130,6 +130,11 @@
<xsl:text> [</xsl:text><xsl:value-of select="@url"/><xsl:text>]</xsl:text>
</xsl:template>
+<xsl:template match="varlink">
+<xsl:apply-templates/>
+<xsl:text> [</xsl:text><xsl:value-of select="@varurl"/><xsl:text>]</xsl:text>
+</xsl:template>
+
<!-- xref -->
--- finkdoc-website.xsl-orig Sun Jun 22 20:22:59 2003
+++ finkdoc-website.xsl Sat Jun 28 20:08:06 2003
@@ -266,6 +266,10 @@
<a href="[EMAIL PROTECTED]"><xsl:apply-templates/></a>
</xsl:template>
+<xsl:template match="varlink">
+<a href="[EMAIL PROTECTED]"><xsl:apply-templates/></a>
+</xsl:template>
+
<xsl:template match="xref">
<a><xsl:attribute name="href">
<xsl:if test="boolean(@chapter)"><xsl:value-of select="@chapter" />.php</xsl:if>
-------------------------------------------------------
This SF.Net email sponsored by: Free pre-built ASP.NET sites including
Data Reports, E-commerce, Portals, and Forums are available now.
Download today and enter to win an XBOX or Visual Studio .NET.
http://aspnet.click-url.com/go/psa00100006ave/direct;at.asp_061203_01/01
_______________________________________________
Fink-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/fink-devel
