[Mulgara-dev] new documentation

thomas thomas at stray.net
Wed Dec 13 18:45:38 UTC 2006


hi,

i converted the documentation from the old kowari version to a slightly 
upgraded mulgara one.  i changed no text (at least not by purpose) but 
quite a few other things. most obviously the layout has changed. the 
documentation looks like the mulgara.org website but there's also a new 
style which you can choose from the menue top right (on modern browsers 
only) which is a little bit "un-styled". but more things changed under 
hood. there are no frames anymore (you can now bookmark pages!) and the 
page-names are names, not numbers. for a list of which numbers match to 
which names see below. at lot of superfluous markup has been removed. i 
also rearranged the site structure (but at least the overview-section needs 
more work). some navigational elements like the "previous" and "next" 
buttons have been removed since i found them rather useless and hard to 
maintain (but they are still in the source so they can be brought back if 
somebody cares).

there is some work left which i can't do but that should be done before the 
new version get's online. in the meantime you can have a look at 
<http://fabri.cc/index.html> to get an idea.

the following things still need to be done:

*
i had to do a lot of search&replace and it may well be that i accidently 
deleted or changed stuff on the way. so please check the site for those 
errors. check the pages you wrote or that you know very well.

*
licensing is a little bit broken
there are four places where licensing is mentioned
/overview/legal.html
/overview/legalinfo.html
/overview/license.html
/overview/semanticstore.html
some links points to osl 3.o, while the text says osl 1.1. another link 
points to mozilla license. didn't want to touch that stuff, but someone 
should.

*
/overview/krule.html contains a northrop grumman copyright statement.
and i'm not sure if the overview-section is the right place for this page.

*
/overview/news.html seems rather superfluous since there's also a news 
section on www.mulgara.org

*
descriptorhw.html contains tucana screenshots. is that okay legally?

*
a lot of links to the outside world are broken. a complete list is below. 
perhaps someone want's to correct them?

*
the overview sections contains some documents that could be consolidated, 
like eg the legal informations.
/overview/tools.html could be removed.
/overview/index contains also documentation.htm
but for a start i think the site structure is already much better than with 
the old version

*
someone should check the metadata in the head ( /includeMiddle.inc)
what to do with the dc.creator tom adams?
what to do with the dc.contributor?
what about the copyright statement?
despite my first impression the description and keyword metadata are not 
very detailed and could be improved. but i know that's a lot of work. for 
more details on changes in the metadata see below

*
i worked on a checkout from last saturday, december the 2. since i handled 
this checkout unappropriatly i can't tell if any changes to the pages have 
been made since then. i can only say that if changes where made, they where 
not transferred to the new site :-( but they are not lost but got backuped 
to trunk/docs/oldSite :-D . i'm still struggling a bit with subversion...


finally, some words about adding new pages:

there is a file called /template.html which should be used for new pages. 
please follow the directions therein about adding title, keywords and 
innerpage navigation. additionally, to be visible on the site the page has 
to be added to the
navigation, which is done by editing the file "includeTOC.inc" within the 
same
directory the new page resides in(!). there is one includeToc.inc per 
directory and they get included into the site recursively.
from these includeTOC.inc files two navigational facilities get constructed 
and rendered on the website: a navigation on the lefthand side of each page 
and a page called toc.html, which contains all pages and all innerpage 
navigations. they are both constructed from the same incudesTOC-files. that 
way you
only have to edit the navigation one time - a solution that i'm quite proud 
of ;-)
i hope it actually works for you...
adding a new directory within the root directory is not very hard either, 
just some cut&paste... well, that may not be entirely true, but i'm too 
lazy to really explain it. just ask me if you run into problems

see below for
*
a list of changes to the head section
*
a list of broken links

*
list of old file names and the corresponding new ones. it doesn't contain 
the directory-path, sorry.

everything is in the repositiry at 
<https://mulgara.org/svn/mulgara-web/docs/site>. go ahead! :-)

ciao
thomas


mailto:thomas at stray.net
http://stray.net




<modifications to the head>
meta DC.Modified -> 2006-10-01 		                       // weil zu diesem 
zeitpunkt die mulgara doc initialisiert wurde
<meta name="location" content="Global" />                       // deleted
<meta name="document-distribution" content="Global" />  // deleted
<meta http-equiv="dialect" content="AU" />                      // deleted
<meta http-equiv="language" content="English" />             // deleted
<meta http-equiv="window-target" content="_top" />      // deleted
<meta name="DC.Creator.Address" 
content="http://www.adams.id.au/tom/index.php" /> 	//del (doesn't work 
anymore)
<!--<meta name="DC.Contributor" content="Andrew Newman" />-->
	// decomment and change content to Paul Gearon
<meta name="DC.Subject" content="Mulgara Project Home" />
	// changed to "mulgara semantic store"
<meta name="DC.Description" content="Mulgara Project Home" />
	// changed to "mulgara semantic store is a scalable RDF database written 
entirely in Java. It is an Open Source fork of Kowari metastore."
<meta name="description" content="Mulgara Project Home" />
	// dito
<meta name="Generator" content="AuthorIT"> 					// del
<meta name="DC.Type" content="Text.Homepage.Personal" />
 	// changed to
	<meta name="DC.Type" 
scheme="http://memory.loc.gov/ammem/award99/icuhtml/dcguide.html" 
content="Text.Homepage.Organizational" />
<meta name="copyright" content="Copyright &copy; 2003, Kowari Project" />
	// changed to 2006 Mulgara Project
<meta name="DC.Rights" scheme="URI" 
content="http://www.kowari.org/about/index.php#copyright" />
	// that page doesn't even exist anymore ;-)
	// changed to <meta name="DC.Rights" scheme="URI" 
content="http://opensource.org/licenses/osl-3.0.php" />
</modifications to the head>





<broken links>
Status,To,From,Line
Failure,/1081.htm,/backofbook.html,386
Failure,/inferencing/infersummery.html,/backofbook.html,545
Failure,/inferencing/api/sofa/index.html,/inferencing/inferexample.html,304
Failure,/inferencing/api/sofa/index.html,/inferencing/sofa.html,337
Failure,/itqloperations/170.htm,/itqloperations/nodetyping.html,225
Failure,/itqloperations/176.htm,/itqloperations/nodetyping.html,242
Failure,/itqloperations/187.htm,/itqloperations/nodetyping.html,256
Failure,/integration/api/jrdf/index.html,/integration/jrdftutorial.html,299
Failure,/system/api/org/kowari/itql/ItqlInterpreterBean.html,/system/itqlbean.html,253
Failure,/overview/OSL-3.0.txt,/overview/legalinfo.html,266
Timeout,https://sofa.dev.java.net/,/inferencing/inferexample.html,300
Timeout,https://sofa.dev.java.net/,/inferencing/sofa.html,306
Timeout,https://sofa.dev.java.net/doc/,/inferencing/sofa.html,308
Timeout,http://java.sun.com/j2se/1.4.2/install.html,/inferencing/sofa.html,324
Failure,http://jakarta.apache.org/lucene/docs/systemproperties.html,/itqloperations/fulltextmodels.html,229
Timeout,http://jakarta.apache.org/lucene/docs/queryparsersyntax.html,/itqloperations/fulltextmodels.html,281
Timeout,http://java.sun.com/j2se/1.4.2/install.html,/integration/jrdfprereq.html,280
Failure,http://localhost/jspdemo/index.jsp,/integration/jsptutorial.html,432
Robot 
Exclusion,http://inline.perl.org/inline/home.html,/integration/perl.html,267
Robot 
Exclusion,http://inline.perl.org/java/home.html,/integration/perl.html,267
Timeout,http://java.sun.com/j2se/1.4.2/install.html,/integration/resolverpre.html,277
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorvcar
d.html,246
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorvcard.html,247
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorlist.html,206
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorlist.html,288
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorlist.html,313
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorlist.html,359
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorlist.html,369
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorhw.html,208
Timeout,http://www.w3.org/style/xsl/,/descriptors/descriptorex.html,218
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,213
Timeout,http://localhost:8080/webui/,/descriptors/descriptorsfaq.html,222
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,231
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,282
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,299
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,319
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,329
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descriptorsfaq.html,386
Timeout,http://www.w3.org/style/xsl/,/descriptors/querytag.html,223
Timeout,http://localhost:8080/webservices/descriptor/index.jsp,/descriptors/descwhat.html,208
Failure,http://www.angelite.nl/aquamarine/,/system/jrdf.html,263
Timeout,http://www.w3.org/style/xsl/,/system/soap.html,251
Timeout,http://www.w3.org/style/xsl/,/tutorial/convertingxml.html,207
Timeout,http://www.xslt.com/resources.shtml,/tutorial/convertingxml.html,207
Timeout,http://localhost:8080/webui/,/tutorial/viewer.html,193
Timeout,http://www.slashdot.org/,/tutorial/itqlbasics.html,375
Failure,http://www.semanticweb.org/library/,/overview/links.html,356
Failure,http://www.musicbrainz.org/products/server/download.html,/overview/links.html,397
Timeout,http://mulgara.org/jira,/overview/contact.html,273
Failure,http://w3.org/%20%5Co%20w3c%20homepage,/overview/aboutsite.html,279
Timeout,http://w3.org/tr/xhtml1,/overview/aboutsite.html,279
Robot 
Exclusion,http://oss.software.ibm.com/developerworks/opensource/license10.html,/overview/optcomponents.html,322
Failure,http://quickutil.sourceforge.net/view/main/jxquick,/overview/optcomponents.html,341
Failure,http://jxquick.sourceforge.net/quick3/license.txt,/overview/optcomponents.html,349
Failure,http://quickutil.sourceforge.net/view/main/jxquick,/overview/optcomponents.html,368
Failure,http://jxquick.sourceforge.net/quick3/license.txt,/overview/optcomponents.html,376
Timeout,http://xml.apache.org/soap/index.html,/overview/oscomponents.html,286
Failure,http://barracudamvc.org/barracuda/index.html,/overview/oscomponents.html,313
Failure,http://xmlc.enhydra.org/software/license/index.html,/overview/oscomponents.html,321
Failure,http://beepcore.org/beepcore/about_publiclicense.jsp,/overview/oscomponents.html,348
Failure,http://castor.exolab.org,/overview/oscomponents.html,367
Failure,http://castor.exolab.org/license.html,/overview/oscomponents.html,375
Failure,http://jetty.mortbay.org/jetty/license.html,/overview/oscomponents.html,510
Timeout,http://groups.yahoo.com/group/jetty-discuss/message/2686,/overview/oscomponents.html,518
Timeout,http://www.sablecc.org,/overview/oscomponents.html,564
Failure,http://xmlc.enhydra.org/software/license/index.html,/overview/oscomponents.html,645
Failure,http://xmlc.enhydra.org/software/license/index.html,/overview/oscomponents.html,653
Timeout,http://mulgara.org/jira,/index.html,195
</broken links>



<rename>
indexpage.htm	backofbook.html
170	alias
171	backup
174	commit
176	create
178	delete
179	drop
180	execute
181	help
182	insert
183	load
184	quit
185	restore
186	rollback
187	select
195	set
223	comment
230	itqlbasics
254	itqloperations/index
255	views
257	fulltextmodels
262	datatypingmodels
271	itqlcommands/index
415	viewer
417	loadingrdf
419	convertingxml
485	jsptaglib
526	itqlshell
527	soap
528	itqlbean
530	driver
571	descriptors/index
572	nsdesc
573	querytag
574	descriptortag
575	reserved
576	descriptorsfaq
597	mistakes
618	descwhat
619	descadvantages
746	perl
752	links
779	descriptorex
795	descriptorhw
802	descriptorlist
920	descriptorvcard
947	jena
990	jsptutorial
1007       overview	
1012	index
1061	faq
1076	contact
1090	about
1091	aboutsite
1092	accessibility
1093	copyright
1094	htmlcss
1095	license
1128	legal
1129	legalinfo
1132	oscomponents
1133	suncomponents
1134	optcomponents
1139	install
1163	downloads
1225	tutorial
1226	sysreq
1227	starting
1232	itql
1236	itqlshellsession
1246	sysarch/index
1350	documentation
1452	news
1565	integration/index
1636	trademarks
2466	jrdf
2467	jrdfgraphs
2511	jrdfmemory
2512	jrdfconcol
2513	jrdfexamples
2526	jrdftks
2528	jrdfvisitor
2552	resolvers/index
2553	resolverdbclass
2622	sofa
2641	inferintro
2642	infersitu
2643	infersemweb
2649	infersummery
2686	resolverhttpmp3
2687	resolverpre
2689	resolverfactories
2693	resolverwrite
2697	resolverwrapper
2701	parsers
2707	contenthandlers
2714	compiling
2720	integrate
2725	infermulgara
2733	inferexample
2737	inferencing/index
2779	nodetyping
2800	owl
2801	entailment
2816	consistency
2827	ontomanage
2892	jrdftutorial
2893	jrdfprereq
2900	jrdfcreategraph
2904	jrdfcreatenodes
2905	jrdfaddtriples
2906	searchgraph
2911	jrdfreify
2912	jrdfremove
2951	statements
3002	jrdfapis
3074	convertrdbms
3183	resolveprot
3184	contenthandlersdev
3201	filesysmodel
</rename>




More information about the Mulgara-dev mailing list