[fossil-users] usability of in-project documentation
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 not seasoned fossil users themselves I can envision quite a few problems. Firstly, fossil has undocumented index file support, and the index file name is hardcoded in the fossil source. Interestingly, this index file 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. 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 redirect to tip or other configurable branch or just list branches (and include ckout 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 was served through this url it would necessarily have broken links. Or the links 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 about the 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/ I also notice that while the CSS is customizable the HTML templates are not. While this is not much of a problem for many projects in some cases you would want to reorganize the page layout and/or add additional elements. At the very least adding some more divs off which to 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 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. 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. Thanks Michal ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] usability of in-project documentation
On Fri, Aug 3, 2012 at 11:48 AM, Michal Suchanek hramr...@gmail.com wrote: huge snip I also notice that while the CSS is customizable the HTML templates are not. While this is not much of a problem for many projects in some cases you would want to reorganize the page layout and/or add additional elements. At the very least adding some more divs off which Hi Michal, FWIW: the up-coming/in-development custom pages/commands support will allow one to do this more easily. Once that is in place, it is very possible that we will (at least be able to) replace the current header/footer mechanism on top of the templates bits which the custom pages need. 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 suspect the main problem there is that fossil lacks triggers/email notifications (for portability reasons), and if the ticket doesn't get noticed in the first page of the timeline view (the first 20 entries) then it probably goes unnoticed more often than not. 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. If you have picked out patches from tickets which you know to work, i would be willing to get them integrated provided that: a) it makes sense to do so. Some feature requests don't fit well into fossil's world view. b) The patches are still current vis-a-vis the trunk. c) There are no objections from Richard or other contributors. This decision ultimately lies with Richard, by the way, not myself. Have you got the list of ticket numbers (or the patches)? This list doesn't accept attachments (IIRC), but if you have the patches, please send them to me off-list and i will get to that this weekend. -- - stephan beal http://wanderinghorse.net/home/stephan/ http://gplus.to/sgbeal ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] usability of in-project documentation
On 3 August 2012 14:45, Stephan Beal sgb...@googlemail.com wrote: On Fri, Aug 3, 2012 at 11:48 AM, Michal Suchanek 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 suspect the main problem there is that fossil lacks triggers/email notifications (for portability reasons), and if the ticket doesn't get noticed in the first page of the timeline view (the first 20 entries) then it probably goes unnoticed more often than not. Another problem is that fossil needs a contributor agreement so random patches attached to the tickets are not going to make it into fossil. Thanks Michal ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] usability of in-project documentation
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 not seasoned 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 index file name is hardcoded in the fossil source. Interestingly, this index file 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 your documentation. Once you compile fossil and do a fossil init documentbetter.fossil followed by a fossil ui documentbetter.fossil, Admin Coniguration you 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 redirect to tip or other configurable branch or just list branches (and include ckout 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 was served through this url it would necessarily have broken links. Or the links 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 about the 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 one Your 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 rectify the 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 templates are not. While this is not much of a problem for many projects in some cases you would want to reorganize the page layout and/or add additional elements. At the very least adding some more divs off which to 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
Re: [fossil-users] usability of in-project documentation
On Fri, Aug 3, 2012 at 6:06 PM, Rene renew...@xs4all.nl wrote: I'm not sure I follow you. again fossil has evolved this way. You have a wonderful opportunity to take fossil system and build ...you can set the the first page to anything you want. including index.html He was referring to fossil's (possibly undocumented) feature that if a /doc dir has a file named index.html then it is served as-is, without any of the normal bling wrapped around it. i only recently learned about it. -- - stephan beal http://wanderinghorse.net/home/stephan/ http://gplus.to/sgbeal ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] usability of in-project documentation
On 2012-08-03 18:15, Stephan Beal wrote: On Fri, Aug 3, 2012 at 6:06 PM, Rene renew...@xs4all.nl [1] wrote: I'm not sure I follow you. again fossil has evolved this way. You have a wonderful opportunity to take fossil system and build ...you can set the the first page to anything you want. including index.html He was referring to fossil's (possibly undocumented) feature that if a /doc dir has a file named index.html then it is served as-is, without any of the normal bling wrapped around it. i only recently learned about it. That is not only for a directory called /doc. If I make a directory hans i get also No such document: hans/index.html However as you call the doc page it has 2 forms ** WEBPAGE: doc ** URL: /doc?name=BASELINE/PATH ** URL: /doc/BASELINE/PATH ** since name is nonexisting and path also the default is used tip/index.wiki and then you get No such document: index.wiki If you do have a path /doc/trunk/hans/ I am without words by the fact that is does come back with No such document: hans/index.html while the code says: doc_not_found: /* Jump here when unable to locate the document */ db_end_transaction(0); style_header(Document Not Found); @ pNo such document: %h(PD(name,tip/index.wiki))/p Which probably means that it is not coming there! ;-) -- - stephan beal http://wanderinghorse.net/home/stephan/ [2] http://gplus.to/sgbeal [3] Links: -- [1] mailto:renew...@xs4all.nl [2] http://wanderinghorse.net/home/stephan/ [3] http://gplus.to/sgbeal -- Rene ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
