"What is FreeCAD" and "About FreeCAD"
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
"What is FreeCAD" and "About FreeCAD"
There are two similar introductory pages, "What is FreeCAD" and "About FreeCAD". They overlap in some ways, where they discuss multi-platform aspects, free software aspects, etc. As a newbie, it feels like repetition if I encounter both of them when sequentially reading.
I see several options:
1. make the About FreeCAD page a side reference, not part of the serial reading
2. incorporate About FreeCAD into the What is FreeCAD page
3. leave it in place as the page following What is FreeCAD (still seems repetitive)
4. move About FreeCAD to the end somewhere (doesn't seem like a good idea given its current content)
My inclination is #2
If we go with #2:
2a. Eliminate About FreeCAD entirely; other references to the about page will obviously have to be updated.
2b. Leave About FreeCAD as is for reference by pages outside the manual, but still incorporate its content into What is FreeCAD
Thoughts?
I see several options:
1. make the About FreeCAD page a side reference, not part of the serial reading
2. incorporate About FreeCAD into the What is FreeCAD page
3. leave it in place as the page following What is FreeCAD (still seems repetitive)
4. move About FreeCAD to the end somewhere (doesn't seem like a good idea given its current content)
My inclination is #2
If we go with #2:
2a. Eliminate About FreeCAD entirely; other references to the about page will obviously have to be updated.
2b. Leave About FreeCAD as is for reference by pages outside the manual, but still incorporate its content into What is FreeCAD
Thoughts?
Re: "What is FreeCAD" and "About FreeCAD"
Hi Gary,
A tip: with the wiki button on the Reply toolbar, you can link a page name to the wiki. Select the page name in the text input area, press the wiki button. You'll get this:
which will render as About FreeCAD. Unfortunately, colons are not supported.
The page you're referring to is actually Manual:What is FreeCAD and part of the Manual.
As indicated in the Main Page, the manual "is another, more linear way to present the information contained in this wiki." It's kind of a "sub-domain" (in MediaWiki lingo it's called a namespace) with all its page names starting with "Manual:".
You can't assume that everybody will read the manual. I guess I'd go with option 2b because I don't agree with deleting or moving the About FreeCAD content.
That being said, you bring a very interesting point, and I think we should maybe think about this further.
I've come to think that the About FreeCAD content is really, really dry. It flings a lot of technical terms and acronyms and links that many, if not most newcomers will either have no interest in, or no frame of reference to understand them. I used to think it was important to mention commercial tools similar to FreeCAD, and the page includes Wikipedia links to them. Maybe we should stop giving them free publicity!
I think that Manual:What is FreeCAD is much easier to read.
So maybe we could take this opportunity to replace the About FreeCAD's content with the Manual:What is FreeCAD content. If you think its current content could be improved, all the better.
I understand that duplicate pages is not ideal, managing them separately would not be efficient nor fun. What could be done is to transclude (see Transclusion on MediaWiki) the About FreeCAD page in Manual:What is FreeCAD, in the same manner that templates are used.
In the Manual:What is FreeCAD, you'd replace the content with
{{:About FreeCAD}}
and you're done.
I made a quick try here that we'll delete when we're done (feel free to edit it and play with it):
Sandbox:What_is_FreeCAD
You will notice that there's some stuff that should not appear: the <translate> tags for one thing, and the Docnav template at the bottom. But we could easily get rid of them by editing the About FreeCAD page and adding transclusion markup so that they don't get transcluded. This is mentioned in the Transclusion page I linked above.
We could even for example keep the "About the FreeCAD project" section in the About FreeCAD page, but not have it appear in Manual:What is FreeCAD.
Any way, that's my two cents...
Norm
A tip: with the wiki button on the Reply toolbar, you can link a page name to the wiki. Select the page name in the text input area, press the wiki button. You'll get this:
Code: Select all
[wiki]About FreeCAD[/wiki]
The page you're referring to is actually Manual:What is FreeCAD and part of the Manual.
As indicated in the Main Page, the manual "is another, more linear way to present the information contained in this wiki." It's kind of a "sub-domain" (in MediaWiki lingo it's called a namespace) with all its page names starting with "Manual:".
You can't assume that everybody will read the manual. I guess I'd go with option 2b because I don't agree with deleting or moving the About FreeCAD content.
That being said, you bring a very interesting point, and I think we should maybe think about this further.
I've come to think that the About FreeCAD content is really, really dry. It flings a lot of technical terms and acronyms and links that many, if not most newcomers will either have no interest in, or no frame of reference to understand them. I used to think it was important to mention commercial tools similar to FreeCAD, and the page includes Wikipedia links to them. Maybe we should stop giving them free publicity!
I think that Manual:What is FreeCAD is much easier to read.
So maybe we could take this opportunity to replace the About FreeCAD's content with the Manual:What is FreeCAD content. If you think its current content could be improved, all the better.
I understand that duplicate pages is not ideal, managing them separately would not be efficient nor fun. What could be done is to transclude (see Transclusion on MediaWiki) the About FreeCAD page in Manual:What is FreeCAD, in the same manner that templates are used.
In the Manual:What is FreeCAD, you'd replace the content with
{{:About FreeCAD}}
and you're done.
I made a quick try here that we'll delete when we're done (feel free to edit it and play with it):
Sandbox:What_is_FreeCAD
You will notice that there's some stuff that should not appear: the <translate> tags for one thing, and the Docnav template at the bottom. But we could easily get rid of them by editing the About FreeCAD page and adding transclusion markup so that they don't get transcluded. This is mentioned in the Transclusion page I linked above.
We could even for example keep the "About the FreeCAD project" section in the About FreeCAD page, but not have it appear in Manual:What is FreeCAD.
Any way, that's my two cents...
Norm
Re: "What is FreeCAD" and "About FreeCAD"
Thanks, I think you've told me that before. I'm a slow learnerNormandC wrote: ↑Mon Dec 31, 2018 11:39 pm A tip: with the wiki button on the Reply toolbar, you can link a page name to the wiki. Select the page name in the text input area, press the wiki button. You'll get this:
which will render as About FreeCAD. Unfortunately, colons are not supported.Code: Select all
[wiki]About FreeCAD[/wiki]
If colons are not supported, then the "wiki" feature is more or less useless when referring to the manual? Or how should one use it if referring to the Manual?
I thought the page immediately following What is FreeCAD was supposed to be Feature list, but maybe I'm confused from the About FreeCAD page. Should the Feature list be in the manual, in any case? I found it useful because it brought out some things not directly related to workbenches, but maybe not needed at that point in the manual. It also struck me as somewhat of a strange mixture of a few workbench highlights and general features, so maybe best left out at this point.As indicated in the Main Page, the manual ... with all its page names starting with "Manual:".
I think that's a good idea. The one idea which seems relevant to me is that FreeCAD is not a 2D drawing app, and not an animation / organic shape creation app.I've come to think that the About FreeCAD content is really, really dry. It flings a lot of technical terms and acronyms and links that many, if not most newcomers will either have no interest in, or no frame of reference to understand them. I used to think it was important to mention commercial tools similar to FreeCAD, and the page includes Wikipedia links to them. Maybe we should stop giving them free publicity!
Ah, got it. I like that idea a lot. It allows the navigation menus in the Manual pages without cluttering up the outside-the-manual pages.So maybe we could take this opportunity to replace the About FreeCAD's content with the Manual:What is FreeCAD content. If you think its current content could be improved, all the better.
I understand that duplicate pages is not ideal, managing them separately would not be efficient nor fun. What could be done is to transclude (see Transclusion on MediaWiki) the About FreeCAD page in Manual:What is FreeCAD, in the same manner that templates are used.
In the Manual:What is FreeCAD, you'd replace the content with
{{:About FreeCAD}}
and you're done.
Why wouldn't the <translate> tags be included?I made a quick try here that we'll delete when we're done (feel free to edit it and play with it):
Sandbox:What_is_FreeCAD
You will notice that there's some stuff that should not appear: the <translate> tags for one thing, and the Docnav template at the bottom. But we could easily get rid of them by editing the About FreeCAD page and adding transclusion markup so that they don't get transcluded. This is mentioned in the Transclusion page I linked above.
Separate issue: Is there a way to shift text up to utilize the space to the right of the contents? Formatting-wise, it would be nice to have a short intro paragraph with a reduced image to the right of the contents.
I will try to work on all this tomorrow.
Re: "What is FreeCAD" and "About FreeCAD"
A sequencial, book-like manual is really something different than a wiki. One thing we learned with this wiki is that it quickly becomes extremely hard to keep its structure linear. This is the real nature of a wiki, to be a kind of shapeless propagating non-structured "thing".
That's basically why I started to write the manual, and why i did it outside of the wiki.
Of course we should always go for cleaning things, avoiding duplication, reuse components, etc, but I think we should always keep this "separation" in mind, otherwise very quickly we will loose the linearity of the manual. People will start linking and reusing and propagating its pieces in other structures, and soon impossible situations will arise where a same page should be at two different positions in the book or impossible to include. Believe me, there was a time when I tried to maintain the whole wiki linear
In this case, of course you are right, reading one of these pages after the other is silly. Maybe we should just consider both pages have different uses and remove the "About FreeCAD" link from the bottom of Manual:What is FreeCAD?
That's basically why I started to write the manual, and why i did it outside of the wiki.
Of course we should always go for cleaning things, avoiding duplication, reuse components, etc, but I think we should always keep this "separation" in mind, otherwise very quickly we will loose the linearity of the manual. People will start linking and reusing and propagating its pieces in other structures, and soon impossible situations will arise where a same page should be at two different positions in the book or impossible to include. Believe me, there was a time when I tried to maintain the whole wiki linear
In this case, of course you are right, reading one of these pages after the other is silly. Maybe we should just consider both pages have different uses and remove the "About FreeCAD" link from the bottom of Manual:What is FreeCAD?
Re: "What is FreeCAD" and "About FreeCAD"
<translate> tags are internal and should not show up in the page.
Look at the Manual's table of contents. What follows after "What is FreeCAD" is Manual:Installing. Remember, every page that's in the Manual starts with Manual:. Any page that doesn't is not part of the manual but part of the wiki at large.
It should be doable, as can be seen for example here: PartDesign_Workbench. It does annoy me to have to scroll down so much because of the length of the TOC.
I also think it would be useful to collapse/expand the Manual's TOC as can be done with regular TOCs.
The problem is that the Manual's table of contents is a template embedding a template. Template:Manual:TOC is what is called in Manual pages; but its content is another template (Manual:Summary) inside <div> tags with a "toc" styling I have no clue how to search for. It's possibly a css style sheet somewhere.
Yorik is the one who created the stuff, so he'll be the one to answer that.
-
- Veteran
- Posts: 2611
- Joined: Tue Feb 21, 2012 8:07 pm
- Location: Torino - Italy
Re: "What is FreeCAD" and "About FreeCAD"
You can use the /en inclusion
Code: Select all
<languages/>
<translate>
<!--T:1-->
{{docnav|Manual:Introduction|Manual:Installing|Manual:Introduction|Manual index}}
<!--T:2-->
{{Manual:TOC}}
<!--T:3-->
{{:About FreeCAD/en}}
</translate>
Re: "What is FreeCAD" and "About FreeCAD"
Agreed; that's also what makes it hard to use as an introductory / learning tool, and why the book is a good idea.yorik wrote: ↑Tue Jan 01, 2019 3:14 pm A sequencial, book-like manual is really something different than a wiki. One thing we learned with this wiki is that it quickly becomes extremely hard to keep its structure linear. This is the real nature of a wiki, to be a kind of shapeless propagating non-structured "thing".
You have my sympathy ! But I agree, keeping the separation in mind is important.I think we should always keep this "separation" in mind, otherwise very quickly we will loose the linearity of the manual. ... Believe me, there was a time when I tried to maintain the whole wiki linear
I agree the About FreeCAD link should be omitted.Maybe we should just consider both pages have different uses and remove the "About FreeCAD" link from the bottom of Manual:What is FreeCAD?
But I also agree with Norm about the dry tone and less than useful enumeration of other projects and libraries aspect of the About page. I created a [wiki]Sandbox:About FreeCAD[/wiki] page that I think is probably more useful, mostly taken from reworked [wiki]Manual:About FreeCAD[/wiki] It seems to me that in this particular case, at least at the moment, it is usable as the About FreeCAD manual page as well.
I also modified norm's [wiki]Sandbox:What is FreeCAD[/wiki] page to use it, but as he pointed out, the template for transclusion doesn't seem to work with the colon so it's difficult to envision.
Thoughts?
I keep thinking once I get past this intro bit things will go smoother...
Re: "What is FreeCAD" and "About FreeCAD"
That doesn't seem to be any different than
Code: Select all
{{:About FreeCAD}}
In any case, it doesn't seem to have any effect with
Code: Select all
{{Sandbox:About FreeCAD/en}}
-
- Veteran
- Posts: 2611
- Joined: Tue Feb 21, 2012 8:07 pm
- Location: Torino - Italy
Re: "What is FreeCAD" and "About FreeCAD"
with the (old)code
the <translate> tags are shown:
with the code shown above, the <translate> tags are not shown: https://www.freecadweb.org/wiki/Sandbox ... _FreeCAD_1
Code: Select all
<languages/>
<translate>
<!--T:1-->
{{docnav|Manual:Introduction|Manual:Installing|Manual:Introduction|Manual index}}
<!--T:2-->
{{Manual:TOC}}
<!--T:3-->
{{:About FreeCAD}}
</translate>
Re: "What is FreeCAD" and "About FreeCAD"
Thanks, I see now.renatorivo wrote: ↑Tue Jan 01, 2019 8:25 pm with the (old)code
...
the <translate> tags are shown:
...
with the code shown above, the <translate> tags are not shown