You are here

Wiki

Hello,
I see good PDF manual for Qtractor but not much tutorials online. I like OSS but do not have much money, so I donate time instead. I wonder if you interested in setting up a Wiki for Qtractor and other tools. Although PDF covers well I think it helps if people also have online reference. Anyway, if you interested I can help editing Wiki, just a thought. I have edited Wikipedia and one other Wiki for a OSS project before, so I know how to edit well. But I won't lie, I can't host it :) Not a super good offer, I know, but maybe it could help people, even if it is close copy of PDF.

Forums: 
rncbc's picture

a wiki has been created now,

http://sourceforge.net/p/qtractor/wiki/

you'll have to register on sourceforge.net and then i'll give you member rights to edit the wiki as you please.

cheers

Looks good, however, when I try and log in with my source forge account the page never loads. I am using Firefox .

rncbc's picture

now i can't really help you much in there, it looks like a sf.net / browser / user problem ...
try whether you can access the wiki without signing in, or whether it works after you sign in again?
http://sourceforge.net/p/qtractor/wiki/Home/

cheers

Hi,
This is quite weird but there isn't any problem when I'm signed out. I'll try with a different browser.

Moved from another thread:
i would just suggest joining the higher standard in writing excellence of the (pretty) older user manual (.odt) with the accessibility and top-notch friendliness of the (not so)newer quick start guide and user manual (.epub), as much as humanly possible ;)

Yes, looking at the both of them, I can see what you mean. I would be happy to do some grunt work in this regard, but I'm not highly skilled in document format conversions etc... I'm not opposed to learning, though. The sourceforge wiki uses markdown, so if we were to use that as a base, we could build web and print documents from that. I think the important thing is to have a good web version of the docs, personally. Epub is basically html, so that might also be a good base format if not trying to get it all on the wiki.

@planar2 - I didn't have any trouble with the wiki using firefox, as long as cookies are enabled, etc.

The 3.0 manual has been wikified, more or less. This is a really nice document, in my opinion, and hopefully most of it can be retained with a little updating... unfortunately, I'm not (yet) intimately familiar with qtractor enough to know which sections need updating. Also, the references still need moving from the appendix to the pages that refer to them, at which point an appendectomy may be in order. If the manual can be kept to ~6 wiki pages or so, it won't be too hard to collect the markdown and create an epub or html page once things are up-to-date. Hope I've got the right idea... :)

rncbc's picture

excellent. one suggestion, if you don't mind, please prefix all pages with something or distinctive label. eg. "Qtractor 0.3.0 User Manual - ..." or "Q030 - ..." for short. if you ever get to make it also from the last quick-start user guide & manual, i would give it a "Qtractor 0.5.x User Manual - ..." or "Q05X - ..." prefix, for instance... the purpose of this is to freeze the original manuals as baselines in the whole wiki set and then start with a brand new scratch set or whatever, probably with no prefix at all.

hope you get what i mean
cheers

...the purpose of this is to freeze the original manuals as baselines in the whole wiki set and then start with a brand new scratch set or whatever, probably with no prefix at all.
Good idea, I tried to do this with the "Qtractor Manual 3.0" page, but the wiki choked on it, so I'll have to try again. In any case, the pages prefixed with "Manual" can be updated in the meantime - they've already begun the transformation from print to wiki mode. It seems to me that any wiki page that's a part of a larger document should have a document title prefix, for cohesion purposes. I'll try to get to the quick-start guide soon, as well.

Old 0.3.0 manual has been added to wiki pages verbatim (in three parts, because of page size limitations). It's about as close of a representation as the wiki medium makes feasible, anyway. If the wiki gives you the option, you can go ahead and "freeze" the pages after looking them over and making any changes you feel like...

rncbc's picture

you're doing a great job. many thanks indeed.

however, at the the time of this comment, i still can't figure out which pages are of which manual thought. the suggested Q030 / " Qtractor 0.3.0 User Manual - ..." and Q05X / "Qtractor 0.5.x User Manual - ... " prefixes aren't being used yet, at least in a uniform way, are they?

on the side, the whole wiki may well get frozen (as in freeze:)) or exported into a json/zip file anytime. then it would be just a matter of custom scripting to convert the whole bundle into something like xhtml and then .epub or else. just guessing, but probably there are some ready-made scripts for just that, otherwise it might be a good weekend project on our own, what you say?

cheers

So far, the pages I've created have names that begin with one of the following:

"qtractor 0.3.0 maunual" - these are the old 0.3.0 manual contents, copied to the fewest number of pages possible (which turned out to be three) with an attempt to preserve at least the semantic formating from the .odt file, but without any attempt to add wiki functionality... for use as a reference, as you said.

"manual" - these are (so far) the same content as above, but broken into a page-per-chapter, with linking index, to make them more editing-friendly (although chapter 4 is still quite large) and with some small amount (so far) of cleaning up to form the basis for a maintainable wiki-manual.

"qtractor 0.5.x" - these are parts of the newer manual/quick-start guide, also for reference... I'm not sure how much further I'll get with this, because it's honestly kind of a mess. The semantic markup in the epub html files is inconsistent, which means the output from the markdown conversion script I'm using has needed a lot of tedious cleaning up (Vim makes it less painful, but still...) to resemble anything coherent on the wiki page (the numbered list magic via indenting was particularly problematic). There's a docbook source file available at the slackermedia repository, so if I try to do the rest, I may work from that, in case it's been improved in the meantime.

My thinking is that if the unversioned "Manual" pages in the wiki can be kept up to date with development, they can be periodically compiled into "version x.x.x" epubs or whatever else you want to publish it as. Assuming that sourceforge gives you direct access to the wiki contents in markdown or some other reasonable form, this shouldn't be to hard. Even scraping it from the wiki interface wouldn't be too bad if the page count is kept close to what it is currently. If having it on the wiki makes the content maintainable (crowd-wise or otherwise), then it seems worth the infrequent trouble to gather it up. :)

[EDIT] Also, it looks like the wiki pages can be freely renamed after being created, so feel free to change any of them to whatever you like.

rncbc's picture

found this: Pandoc - a universal document converter...

might well get useful in our intents to convert the wikis into .epub without extreme ammounts of effort :) now, we only have to find the means or scripts to convert the sf.net's wiki export bundle format (JSON/Zip) into something that Pandoc can swallow :P

cheers

Yep, I was led to Pandoc in my initial search for document conversion utility, but it turns out that I would need to build a bunch of haskell dependencies to run it on slackware, and the online demo only allows 1000 characters... but I'm sure it's great. :)

Maybe I'll use the JSON as an excuse to finally Learn Python the Hard Way...

I've learnt a few new things from this thread recently, which I don't believe are documented in the wiki. I'd like to add this information, but what's the best way to do this? Should I add directly (would need access), or submit to someone?

rncbc's picture

you can do it directly now: yuba is now a member of the qtractor wiki editors board :)

cheers

[EDIT:] yaba is now yubatake.

Just tried to edit a page but am getting "[Error 403] Edit access required". My username is there in Project Members, so I'm not quite sure why this is. I tried another browser (I see someone had trouble with Firefox), plus several different pages, but it doesn't seem to work.

rncbc's picture

plese, would you try again?

some explicit but rather generic permissions were given to members of the whole project, not only to the wiki.

seeya

Still not working, I'm afraid :-( I'm clicking the "Edit" pencil in the top right - I presume that's correct?

rncbc's picture

I'm clicking the "Edit" pencil in the top right - I presume that's correct?

yes, that should be correct.

also there should be a "Create Page" button when you're there... try clicking on it then. if it not exists you either are not logged in as you should or you're not that yuba anyhow. now, i'm out of options in your case :( are you sure you're logged in exactly as yuba when you try?

byee

[EDIT:] yaba is now yubatake.

I double-checked everything and was correctly logged in, but I still couldn't edit and there was no Create Page button. Then I noticed that I can't even edit my personal page on sourceforge (I get the same error) and that the account creation date is years before I actually created it. So it looks like my sourceforge account may be broken :-)

I'm not sure what their support is like, but will contact them and see if they can help. If they can, I'll hopefully then be able to update the wiki.

I've spoken to the sourceforge people and the issue was that my username and display name differed and there was a completely separate user called "yuba". I've now unified these names.

So could you remove yuba and add yubatake please?

Sorry for the confusion :-(

rncbc's picture

sure, done.

Thanks very much. I've updated the wiki now and will add anything else I come across in the future.

AutoStatic's picture

Hi Rui,

Could you add me as a Wiki member too? I think I could contribute a thing or two. TIA.

Jeremy

rncbc's picture

sure. Jeremy is now a member of the wiki editors.

please test by trying to create a new wiki page and see if you don't suffer from same permissions problem from yuba...

cheers

AutoStatic's picture

I could successfully create a page and delete it afterwards.

I've been saying I'd help out with the qtr docs for some time so I thought I'd post here to say I've finally done something. So far I've edited and updated the first two chapters of the wiki manual:

https://sourceforge.net/p/qtractor/wiki/Manual%20-%201%20Introduction/

https://sourceforge.net/p/qtractor/wiki/Manual%20-%202%20Installing%20an...

I'll be editing and updating the rest as I find time.

rncbc's picture

it's never too late ;)

thanks Dan

rncbc's picture

hi everyone,

hell yes, after a very long time, almost as taken into forever deeps and back, i got something working in this topic, finally: somewhat automated the conversion of the whole or part of the online sf.net/p/qtractor/wiki into an epub/pdf [1] and guess what, plain html [2].

check this out:

  1. Qtractor Manual & How To's: [epub] [pdf]
  2. Qtractor Wiki Home: [html]

please let me know what you think of this.

if nothing or no one stands against, i am willing to give all this a regular update and, most importantly, make it officially into the project web, ie. qtractor.sf.net(aka. qtractor.org)/doc perhaps?.

[UPDATE] once again, all has been updated from wiki+attachments export as of qtractor-backup-2017-03-08-102040 and the epub/pdf are time-stamped as 2017-03-08 10:23+0000.

cheers

Hi Rui,

This looks very useful - thanks. If you're happy to include it in the main project that's great.

I haven't used e-books up to now due to tracking/DRM concerns, so can't comment on how this compares to others, but I had a look at it (using calibre) and the html version and saw a couple of things:

E-BOOK
- "Manual - Table of Contents" chapter is on p147, but should be at the start (or may not be needed at all with an e-book, as the reader takes care of it - I'm not sure what the general practice is)

- I don't suppose we need the "Manual Draft" section, as the only thing in there was added to the wiki a long time ago, but it could be an appendix if you particularly want to keep it (e.g. as a catch-all in case anyone adds to this section on the wiki). *It's also in the html version (along with the old manuals, which aren't in the e-book), but I think it's fine there as it's in the browser like the wiki is anyway

- Links don't seem to work properly. Seems to be a far-reaching problem, but to give two examples:

3.6 Next Steps
Specifically, see [here] for more information on working with MIDI and [here] for audio.

Both these links work correctly in the wiki (and have done since before 2017-02-20 as far as I know) but in the e-book they both go to the start of Chapter 4.

4.8.2. Connections
a task which is achieved via the [Connections window].

Link doesn't work at all (like many others). In the wiki, it goes to the start of "4.8.2. Connections".

HTML
- "Yassin Philip" link at the start is broken. It goes to your rncbc site, while the wiki one goes to sourceforge. "junkyardsparkle" next to it is fine. It's on this page:
http://www.rncbc.org/datahub/qtractor-doc/Home.html

- The sub-chapters (2.3.1, 2.3.2 etc.) in the Table of Contents are a bit hard to read, as they're all on one horizontal line. The original wiki puts them on separate lines, indented. This is the page:
http://www.rncbc.org/datahub/qtractor-doc/Manual%20-%20Table%20of%20Cont...

- Same links issue as e-book (though "4.8.2. Connections" goes back to the start of the chapter)

That's what I've seen so far. Will be happy to test again once any amends are made.

Pages

Add new comment