And hopefully we will soon have string interpolation in Nim (PR). Then it would be something like this (or similar, language is still in discussion):
import strinterp
echo fmt"$x%.4f"
let num = 10.123456789
echo( formatFloat(num) )
Could I get a little help here to make this work.
import strutils
let num = 10.123456789
echo num.formatFloat(ffDecimal, 4)
Thanks a whole lot!
The Docs really need to get better by showing clear examples like this for just about everything. It took way too long for me to search and not even find this, and had to resort to asking how to do this here. I also agree the semantics for doing this has to become a lot shorter/simpler/clearer.
I don't mean to go off, but outputting is such a standard thing to do in any language it should be readily available in the Docs to show users how to deal with the various cases.
Thanks again.
RFC:
if strutils has toBin(), toHex(), toOctal(), intToStr()
and from system.nim, the $ operator is described as
The stringify operator for an integer argument. Returns x converted to a decimal string. $ is Nim's general way of spelling toString.
why not add a helper proc to strutils as
proc toString(f: SomeReal, prec: int = 8): string =
result = f.formatFloat(ffDecimal, prec)
@bluenote
Correct me if I'm wrong but wasn't string interpolation ("borrowed" from Swift) already done long time ago? Can't it stay library-provided? It's not like every language has it in the core.
The Docs really need to get better by showing clear examples like this for just about everything. It took way too long for me to search and not even find this, and had to resort to asking how to do this here.
When I go to
https://nim-lang.org/docs/theindex.html
and search for "format" there are too many hits but eventually I arrive at "formatFloat". When I search for "formatFloat" I find what is suggested here, if I search for "floatformat" I get a hit to FloatFormatMode pointing me to strutils which contains "formatFloat". The docs say
proc formatFloat(f: float; format: FloatFormatMode = ffDefault;
precision: range[0 .. 32] = 16; decimalSep = '.'): string
At this point you need to be able to read Nim's type signatures. More examples for this proc would be nice indeed but I don't see how they would have helped you in finding the proc in the first place.
just about everything
We have theindex.html that contains links to just about everything. It didn't seem to have helped you. As I keep saying, there are limits to what we can do about the fact that people do not read text on the screen.
I just did the same for Python:
Starting at https://docs.python.org/3/ I go to https://docs.python.org/3/genindex.html then to https://docs.python.org/3/genindex-F.html then to https://docs.python.org/3/library/functions.html#format and I arrive https://docs.python.org/3/library/string.html#formatspec which keeps me puzzled. ;-)
Actually, the only limits of what you can provide in documentation are self imposed.
Writing documentation is an attitude! Either you care about doing it (to benefit/help users) or you don't.
Nim has to compete against lots of other languages, and like cars, smartphones, etc, having the better/best technology doesn't mean you will have the biggest following. People will ultimately use first the things that are accessible, easy to use, and cheap (why do Americans eat so much bad fastfood - because its cheap, the stores are everywhere, and they stay open late when people are hungry).
Your own 2017 Survey specifically lists lack of documentation as one of the biggest deficiencies of this project, but I don't see an active effort to make it better.
https://nim-lang.org/blog/2017/10/01/community-survey-results-2017.html
Let's compare Nim against Rust, two languages promoting themselves as system programming languages. Rust is by far a much harder to learn/use language than Nim, but it knows that, and has created very good documentation (and forum) to help people get their heads (and hearts) around it.
Both Nim and Rust have a document called [Nim|Rust] by Example, but tell me which is more helpful/useful to potential users.
Let's compare their presentation of arrays in each document.
Nim: https://nim-by-example.github.io/arrays/
Rust: https://rustbyexample.com/primitives/array.html
As a potential user I get a much clearer understanding of how to create, access, and print arrays from Rust's docs, with examples for each use case given.
Now let's take a look at Ruby's: https://www.ruby-lang.org/en/documentation/
Granted, Ruby has been around a lot longer than Nim, and has loads of books, videos, and conferences, but it all starts with an attitude of the Ruby community, which is probably The Most Friendly language community in the world. You can find just about anything you want on this page about how to use Ruby, and this is by design. They didn't limit what they could do.
And here's what I mean by attitude for this specific instance of trying to find out about outputting floating points.
I took about three hours, searching the docs and internet, trying to find out how to print out floats to a given precision, and gave up after being frustrated (fed up). Only then did I resort to asking help in the forums. It was first answered by only providing a link to a cryptic (my impression of it) function, which had no examples of how to use it. I had to ask, again, how to use it, and was finally given a specific example of how. And then when I point out none of those functions on that page (and elsewhere) have specific use case examples, instead of saying, "you're right, we'll get on it", you give excuses (there are limits to what we can do).
If I were you all, I'd start immediately upgrading your docs, first by formatting the categories from the point of view of helping potential users (Input/Outputting Data, How to use Files, etc) with clear/concise/helpful use case examples. You can start by copying best practices used in other projects docs.
Would this take a lot of work and effort -- Hell Yes!. But you all need to really understand, you are not only in a battle to win peoples minds, to get them to understand your language, you're also competing to win (and keep) their hearts, so they want to use your language. People can criticize Ruby all they want, but people who use Ruby, and go to its conferences, do so because they love it, even when they move on to other languages (like Elixir).
Actually, this specific discussion should have its own thread, so others can chime in, and not be buried at the end of this thread.
But please take to heart this old saying: You only have one chance to make a first impression.
@jzakiya I have read a lot in this post, but due to my own lack of time I decided to skip most of it (so apologies if somebody mentioned this already).
Why doesn't Nim have better docs? Some reasons:
Nim is a community project. Everybody that works on it, does so out of love for the project. Telling us to "get on it" is unfair and rather ignorant.
To help illustrate my point better: you mentioned Nim by Example and Rust by Example. Both are community driven projects. Check out the people that helped create these projects:
If you want to help improve them then make a PR. Creating documentation PRs is the easiest thing in the world (but also the most boring, which is why people rarely do it). So, what's your excuse? In the time that you've written these posts you could have gone in and fixed the problems instead of talking about them. If you don't know where to find things, then ask, I'll happily guide you.
BTW, could anyone direct me to how index is built/generated ? I hope it is not manual work. I have something in mind I wish to explore.
koch docs builds the documentation. The index is eventually generated by a command like
nim buildIndex -o:html/theindex.html destPath
Where destPath contains the .idx files.
Would it be difficult to enamble doc tool to handle expanded macros? I love generating docs in Rust's macros so I thought it would be really nice when you have repetitive routines as I could use a macro and the user still have nice docs for each routine independently.
nim doc2 does expand macros. (Soon to be renamed into nim doc.)
@dom96 if you want people to voluntarily, out of their concern for the project, and goodness of their own heart, contribute to Nim, first you need to check your attitude, and learn how not to chase people away.
Writing better documentation has very little to do with how much money or people a project has. Like I (and all these links I've been providing) said it's an ATTITUDE. You took whatever time you took, with whatever resources you had, to create the documentation that exists now. Well, take at least the same time and resources to make them better, and stop making excuses.
The most relevant thing you said was you think writing documentation is boring, and it shows!
Instead of telling me what I should/could do you should do it yourself. It ain't my project and I have no responsibility to make it better. The fact that I (and others) take time to inform you all about errors and deficiencies in your project (and you've made it clear this isn't an our project) should be seen as a gift.
You know, you can do what @bluenote has done and try to write some better, correct, and useful documentation. It's amazing how much you can accomplish if you just improved one function/page/module of documentation each day/week/month.
And if you really, really, really want people to contribute to documentation don't require people to jump through the hoop of writing/submitting pull requests. I personally hate making pr's just for documentation, it so primitive. Instead, create a wiki (there's this little project called wikipedia you know), so people who are writers, or willing to write, can actually do documentation in a way that's more conducive to writing documentation versus code versioning.
I know, I know, this would take too much time and effort to implement, and it's much easier taking time and effort to peruse the forums and tell people you won't take time and effort to create better documentation because its too boring.
From a formatting point of view, please don't use the code syntax for bold, it's painful to read.
I think it's completely misplaced to criticize dom96 for not contributing to documentation, he took two years of his time to write an excellent book, make sure that his examples are useful and also that they still compile (which is not easy given the rate of development).
And documentation is universally what most devs always put last, because there is always a new shiny thing, a bug to fix, deadline or just plain taking a breather and enjoy life. I don't think dom was saying that he found documenting too boring but he was explaining why the Nim community didn't contribute as you would like, you even say it yourself, "it's so primitive".
Also there is an interesting Nim cookbook project..
Regarding wikis, if it can be as awesome as Arch wiki, that would be great, now some devs are even saying that this is where information goes to die. If people tell you "Add your solution to the wiki" after getting help on the forum will you do it?
And PRs for doc doesn't even require you to clone Nim repo on your machine, you can just check that the example work on https://play.nim-lang.org/, I fail to see how hard it is for a developer.
Last thing, I would really like you to stop with the passive-aggressive and entitled tone in your posts. While it's understandable to want something you like to improve and succeed, don't lash out within the Nim community, we all want to make it happen: you don't like docs, fine, build a library, blog, contribute to the cookbook/wiki in the thread I linked, add Rosetta Stone examples.
@dom96
Doc writing is boring
Creating documentation PRs is the easiest thing in the world (but also the most boring)
It depends. I, for instance, quite like it. I care (although "deeply" may be a big word) about my users so even if I have no time, energy or I'd like to move to another project, I like to make good docs so that the project is... well... what I call "mature product".
So, what's your excuse?
A few reasons not to do this:
Nim is a community project. Everybody that works on it, does so out of love for the project. Telling us to "get on it" is unfair and rather ignorant.
Then no surprise users have complains and may eventually switch to another language. Most of people don't like "shut up, I do it in my free time anyway". Or so I guess.
@Araq Good to know. I haven't really tried generating comments yet as it's quite new (it wasn't there before I took a break from using Nim). Too bad it doesn't work for submodules (well... actaully, that there are no submodules in Nim). :( But renaming nim doc2 to nim doc seems nice.
@mratsim
documentation is universally what most devs always put last
That's bad news. :( But I like the idea of Nim Cookbook, that's for linking it.
@all Just in case somebody would like to tell me I do-nothing-for-Nim-so-why-keep-grumbling... I gave a few lectures about Nim and even wanted to lead some workshops (I guess it's not my fault people voted for Rust workshops instead). What's more, one of these lectures seems to have some impact as after that I was offered to give another lecture on Nim language elsewhere. Most of people I met who didn't really treat Nim that seriously did so due to lack of popularity (tools and libs are ok, so I guess it's due to docs/tuts and community?) and constantly being in pre-release version.
It seems Araq doesn't really like my way of thinking. I can also see how Araq reacted to pointing out formatFloat's odd behaviour for 0 (which was quite odd to me, too). I, for instance, didn't notice it myself as I don't really use Nim for numerical calculations (I use Fortran). And I think good docs should be treated as kind of test and things should be fixed if these tests prove what they test is unobvious or even worse, erroneous.
I actually agree the behaviour for 0 is odd and never said otherwise.
All I did was offering my help and I tried to find the root cause for why jzakiya spent 3 hours unsuccessfully looking for formatFloat when his/her very own title contained the word format. As a thank-you I never got any real answers (I still haven't btw) and I have to read pamphlets about my "attitude" and that I should be grateful for his precious feedback that from my perspective he actually actively withholds.
There are always at least two sides to look at, from my perspective I'm grateful and humble, I haven't banned him or censored his impertinences. ;-)
I won't participate in this thread any further.
@Araq
I probably mistook the general spirit of your answer for an answer to this particular thing. Sorry then. :-/
Well, I'm puzzled about this particular case (searching for float formating) too, as... well, I've already said this --- if you're looking for a single specific function (which is, luckily, not some fancy operator), it's quite easy to find it. It would be less obvious if it was about some techniques, I'd say. So... I can't give you my answer, as I find index very useful. ;)
Also: ohhh, please, don't say you're nice because you're not censoring people... again. ^^" You're much cooler when you don't use that argument. ;)
Well, I guess this thread is a huge off-top, that's right here. ^^"