#269 Links-mess

open-accepted
Sean Morrison
3
2010-07-08
2010-07-08
andre anckaert
No

Reporting messed-up links in the manual of the very newest download-package is going to be a tedious job. I know, and appreciate, that BRL-CAD is a give-away shop and as Germans say: "Gekriegenes Gaul guckt man nicht in's Maul". But as I was encouraged to report them, here is another, probably typical, one:

http://fotoalbum.seniorennet.be/incl/getimage2.php?imageid=1575565&albumid=18832&typeid=4

It seems that the name of the file where the link points to has simply, and for which sane reason?, been changed from "mged_cmds.html" to "mged_cmd_index.html". And that is indeed the name of the file, that was also in the very latest download-package, where I found what I hope and believe is the real and genuine "oed"-explanation:

http://fotoalbum.seniorennet.be/incl/getimage2.php?imageid=1575566&albumid=18832&typeid=4

And here is MGED's own, (expert-) "oed"-help:

http://fotoalbum.seniorennet.be/incl/getimage2.php?imageid=1575679&albumid=18832&typeid=4

It should not be too difficult to correct in your html-source all the occurrences of the links to the bad file to point to the good one? And change the very newest installer-package to dustribute the right thing? As now I found how to get at the right info it will probably not be necessary to try that solution here.

Since filing a "bug" for every wrong link I stumble over seems no good solution, somebody might perhaps be glad to receive every once in a while a file with a list of links that point to a wrong file or to no file at all?

Discussion

  • Sean Morrison
    Sean Morrison
    2010-07-08

    André, as I mentioned in your previous bug report, you are reading OLD documentation. So old that it's fallen out of maintenance, which is why you are encountering dead links.

    The report is certainly appreciated and is a matter being addressed, but you should still be using the documentation on the main website instead of the built-in html documentation.

    Again, the current manual is at http://brlcad.org/wiki/Documentation

     
  • Sean Morrison
    Sean Morrison
    2010-07-08

    • labels: --> Documentation
    • milestone: --> other bug / workaround
    • priority: 5 --> 3
    • assigned_to: nobody --> brlcad
    • status: open --> open-accepted
     
  • Sean Morrison
    Sean Morrison
    2010-07-08

    You'll hopefully also note in the documentation link I posted that there is an entire tutorial dedicated to the 'oed" command, complete with exhaustive explanation, details on how to use it, and rationale with discussion.

     
  • andre anckaert
    andre anckaert
    2010-07-08

    Sean,

    Yes I have read all you explained. But I have a strong impression that you at BRL-CAD there are waging some kind of a war.

    Much of the basic documents you advise me to use date from around 2001. You said earlier that nothing much has changed meanwhile.

    I like to believe you but I cannot understand why the BRL-CAD 7-14-8 downloaded only some week ago comes with documentation that you say is fallen out of maintenance...

    Here is a link to what BRL-Cad 7-14-8 says about its documentation:

    http://fotoalbum.seniorennet.be/incl/getimage2.php?imageid=1576345&albumid=18832&typeid=4

    When I look in my BRL-CAD folder I find all the html-documentation this little window says must be there. So let me be confused and a little hopeless. BRL-CAD is difficult enough to have reliable help right at hand.

    I have returned to BRL-CAD (from Blender and Sketchup) because this is SOLID 3D and I was promised a new release. I have all the stuff available in the Wiki which is mainly PDFs dating also from about 10 years ago.

     
  • Sean Morrison
    Sean Morrison
    2010-07-09

    It is a war of complexity, size, and limited resources.

    BRL-CAD is very large and the documentation is extensive. There are several *thousand* pages of documentation available across hundreds of manual pages, dozens of books, and more. What is integrated into the mged menus in html form represents a small fraction of that documentation and it's simply not been a high priority to update given everything else we need to work on.

    We have a limited amount of manpower resources and an over abundance of things to work on. Documentation seems like an easy one, and is, so the core developers rely on documentation getting updated by non-developer contributors (by people who can help but can't write code). That way, developers can focus their effort on tasks that best utilize their skills (writing code).

    So my point is to say that your reports are appreciated, and you're welcome to keep submitting them. If you directly update the html source (via whatever means), those would be the most effective way to fix the broken links and/or update the documentation. If you're looking for the long-term plan, those html files need to get converted into the Docbook format and merged with our existing Docbook documentation.

     
  • andre anckaert
    andre anckaert
    2010-07-23

    [b]Meanwhile[/b] I continue to use what I find and try to make the best of it. Or even make it better: see my recent post on the Help-forum.

    As for missing links here is another one:

    [url]http://fotoalbum.seniorennet.be/incl/getimage2.php?imageid=1618717&albumid=18832&typeid=4[/url]

    This is clearly about a file that has been lost somewhere. Someone of you at BRL-CAD should be able to locate it and issue some advice/message to users (of 7.14.8 on Windows) where they, and I, can find it?

    It will be a pleasure for me to report any missing links I fall over. Shall I make a weekly/monthly/... list and mail it somewhere/put it here ? Or what else? You just tell me.

     
  • andre anckaert
    andre anckaert
    2010-07-23

    I recently downloaded the complete 7.16.8-source, including a lot of help-stuff.

    I now notice that much of the same links are missing there and that the stuff is as outdated as that of 7.14.8. For one thing learning more about Edit States is an illusion:

    http://fotoalbum.seniorennet.be/incl/getimage2.php?imageid=1619104&albumid=18832&typeid=4

    Still the MGED Manual html-file says it is made on May 6, 2010. Yeah, the typo has been improved.