On 2012-08-03 11:48, Michal Suchanek wrote:
hello,while the wiki has its entry in the fossil menu and is easy to find the in-project documentation is not so obvious. As a fossil user I have to read the manual to find the docs at all so I would know. The manual is even quite well explained and almost exhaustive.However, if I were to direct people to the in-project docs who are notseasoned fossil users themselves I can envision quite a few problems.
Fossil has evolved this way. However you can do the right thing on your project. so many ways of generating documentation docbook, lyx, asciidoc, html. wiki.
and the generated html can be feed into fossil.
Firstly, fossil has undocumented index file support, and the indexfile name is hardcoded in the fossil source. Interestingly, this indexfile is index.html (only). Having checked index.wiki or README or readme.txt into the repository is no use. You will have to use an index.html with redirect to have one of those files as index.
I'm not sure I follow you. again fossil has evolved this way. You have a wonderful opportunity to take fossil system and build yourdocumentation. Once you compile fossil and do a fossil init documentbetter.fossil
followed by a fossil ui documentbetter.fossil, Admin Conigurationyou can set the the first page to anything you want. including index.html
fossil displays on that page"Enter the pathname of the page to display when the "Home" menu option is selected and when no pathname is specified in the URL. For example, if you visit the url:
http://localhost:8080
And you have specified an index page of "/home" the above will
automatically redirect to:
http://localhost:8080/home
The default "/home" page displays a Wiki page with the same name as the
Project Name specified above. Some sites prefer to redirect to a
documentation page (ex: "/doc/tip/index.wiki") or to "/timeline".
Note: To avoid a redirect loop or other problems, this entry must begin with "/" and it must specify a valid page. For example, "/home" will work but "home" will not, since it omits the leading "/".
"
Second, the doc/ hierarchy behaves very odd compared to what users would expect after visiting sites served by other we servers. The url http://www.fossil-scm.org/fossil/doc contains: No such document: index.wiki This is very misleading. I have no idea where this comes from as 1) there is no possibility that any files reside on this URL 2) index.wiki is not index file of anything I guess if this page was to contain useful content it could redirectto tip or other configurable branch or just list branches (and includeckout in the list when an open repository is served). The url http://www.fossil-scm.org/fossil/doc/trunk contains: No such document: index.html This is more to the point since it complains about non-existence of the undocumented index file. However, if the file did exist and wasserved through this url it would necessarily have broken links. Or thelinks would be broken when served through http://www.fossil-scm.org/fossil/doc/trunk/ or http://www.fossil-scm.org/fossil/doc/trunk/index.html because the latter urls are down one directory in the url hierarchy. Redirection to single URL is required for such file to work.The url http://www.fossil-scm.org/fossil/doc/www again complains aboutthe missing index file. In the current fossil release it would complain that www does not exist, and only allow http://www.fossil-scm.org/fossil/doc/www/
It is called doc. after documentation not after documentroot.and there cannot be anything directly under it. because you can only get documentation from a version. So doc must always be followed by a version.
and then your are at the top of your repo. But it won't let you browse thru those files. You need to target oneYour right it is inconsistent. Richard and many of us are a bit blind sided
from living with fossil. Refreshing that someone takes the time and point that out. It seems like a simple project to rectifythe inconsistent naming convention. (hint hint). I know of an other one. -R I would propose that every command where you have to mention a repo it is
prefixed by option -R
I also notice that while the CSS is customizable the HTML templatesare not. While this is not much of a problem for many projects in somecases you would want to reorganize the page layout and/or addadditional elements. At the very least adding some more divs off whichto hang the style rules would be useful. eg. I was considering to add a background to the page header but noticed that by default the body has 1ex margin which prevents the header background from reaching the sides of the page. Removing this margin starts a cascade of changes
Yeah it ain't called cascading style sheet for nothing :-) But the header and the footer are part of the saving. The body is out of reach. because it has be generated from de data
required to return to remotely sane formatting while stylistic-only header and content div which implements the margin and possibly background in place of the body element would work wonderfully. Is there any chance that the in-repo doc serving is polished at least to the point that it's usable by unsuspecting people just browsing the web without realizing this is in fact a fossil repository. As it is the fossil served pages need to be used very carefully because they are quite fragile compared to what you would expect from, say, static directory structure served off apache.
What do you mean by fragile "fossil served pages"
I am not opposed to writing patches, and all these issues are quite trivial but I am also aware that some patches are rotting in the fossil tickets for years so I guess patches are not what gives you fixed fossil. I can apply them locally but it does not help if I want other people to be able to mirror my repo or use chiselapp, or whatever. And I need to rebuild for every architecture myself since whatever official packages exist will never get my local patches.
Hm, You are a bit of a sceptic. Even before you tried you are convinced that you fail. Just fill in the developer form. Send it to Richard. Even if your patches won't get in the trunk. Then it still will be in the official repository. and you are welcome to update your branch. And everyone who clones the fossil repo get your branch. You could even make the better documentation part of your repo As I said I have used docbook, lyx to generate documentation from de Jim Schimpf book and put that in fossil.
Thanks Michal _______________________________________________ fossil-users mailing list [email protected] http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
-- Rene _______________________________________________ fossil-users mailing list [email protected] http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
