Logged-In As
ACCOUNT
Not Logged In
Create a concept for a documentation browser The NetBSD Project
Status: Closed Time to complete: 144 hrs Mentors: Radoslaw Kujawa, Julian Coleman, Julian Fagir Tags: research, wiki

There are many possibilities to ship documentation together with the distribution. Most operating systems stick to providing their documentation PDF, HTML, cleartext, GNU info or manpages. NetBSD currently uses various formats for documentation, but for this task, this doesn't matter.


In case your system is offline (when the Internet connection shut down, or you are on your notebook), you want to have this information available.
We want to write an offline documentation browser, but the whole user interface is unclear. What kind of links do you provide (remember: A browser might not be available)? How do you select them? By numbering them, by commandline (like vi), by selecting them with cursors? When using cursors, how do you browse? How would you implement a browser history?


This task is not strictly user interface, you also have to research how it is possible. We want to reuse as many tools as possible (like less(1)) as they sometimes fulfill complicated tasks.


In the end, we expect a declaration of how the user interface should look like, such that the programmer can directly start to program this interface. You should not only provide this declaration, but also a reasoning why this choice is the best one, and some conceptual drawings that show your interface "in action".


If this task is interesting for you, we can support you also after Code-In if you want to write such a browser (in C), the actual language for the markup depending on a prior task.

Uploaded Work
File name/URL File size Date submitted
create a concept for a documentation browser.txt 2.7 KB December 09 2012 17:04 UTC
P1040329.JPG 1.5 MB December 09 2012 17:05 UTC
Comments
broccoly on November 27 2012 17:09 UTC Task Claimed

I would like to work on this task.

Radoslaw Kujawa on November 27 2012 17:13 UTC Task Assigned

This task has been assigned to broccoly. You have 144 hours to complete this task, good luck!

broccoly on November 28 2012 15:30 UTC Tanks for letting me do the great task!

Hello there,


 


I am glad to work on the interesting Task.


I did in the last couple ours lots of research and would like to know, how big the documentation content is/or will be, and with what kind of methd they are currently saved.

Radoslaw Kujawa on November 28 2012 16:07 UTC Re: Tanks for letting me do the great task!

As stated in the task description, currently we use mix of man pages (troff), GNU info, clear text, HTML, PDF, recently also markdown, and who knows what else. However, it does not really matter for this task, as this task is about researching (and possibly designing) the user interface. Same with size of the documentation, it does not matter for this task. Naturally, you can always install NetBSD on a real machine, or in a virtual machine and check it yourself if you think that's important. But try to focus on interface side.


Be as creative as you want, try to think about an interface that would be easy to use, yet possible to implement in text mode (preferrably with tools and libraries we already have in base system).


You can try making mock-ups of such interface. 

Aleksej Saushev on December 1 2012 11:30 UTC Progress?

Hi!


You're working on the task for three days.


Please, get in touch with us on #netbsd-code, so that we could help you if you got misdirected, stuck, or just to help you to wrap up.

broccoly on December 2 2012 09:07 UTC Claim Removed

The claim on this task has been removed, someone else can claim it now.

Isaac Rosenberg on December 2 2012 18:16 UTC User Interface

I'm a bit confused on why a browser would not be available. I mean, I understand that sometimes the person will not have internet access, but if the documentation browser were to be written in client-side code, why would it matter? If you have the documentation on your computer, then I don't see any reason why you could not simply open up the documentation browser in the… browser. 

Radoslaw Kujawa on December 2 2012 18:39 UTC Re: User Interface

It's simple: we don't ship a web browser in base system. You'd have to install it first (and you probably can't do it without an internet connection).

Julian Fagir on December 2 2012 20:27 UTC Esp. in critical situations

Especially when you're in critical situations (i.e. the server is down and won't come up again), you won't have internet access nor graphics, and maybe only a crappy console.


And even with a web browser installed, you also need a webserver running to evaluate wiki links or absolute links.


So we need a minimized documentation browser. Something which is very fast, standalone, and does only view documentation, without being forced to have a webserver running. 

Isaac Rosenberg on December 2 2012 21:27 UTC Task Claimed

I would like to work on this task.

Julian Fagir on December 2 2012 21:40 UTC Task Assigned

This task has been assigned to Isaac Rosenberg. You have 144 hours to complete this task, good luck!

Isaac Rosenberg on December 2 2012 23:35 UTC Claim Removed

The claim on this task has been removed, someone else can claim it now.

wmzhere on December 3 2012 05:21 UTC Questions about description

Hi, 


I read the task description and I can't understand it very well.


Did you mean that :


Designing UI and features of an offline doc browser.


The doc browser should support one specific file type.


The details such as link navigation and history should be written.


Draw a ascii graph of this browser.


Additionaly, write C code to implement the browser.


Thank you.

Julian Fagir on December 3 2012 16:05 UTC It is about the UI and features

Yep, it is mainly about the first two things.


In the end, we want an ascii browser which supports a history and link navigation (and maybe even tabs, but that might get too difficult).


The primary goal of this task is to define the requirements for such a browser. What is needed (e.g. history, link navigation, colours?)? What buttons should be defined (e.g. forward, back, switch colour on/off, quit, search, follow link)? What should the screen design look like (should there be a task bar?) - you don't have to do it in ASCII, but maybe just draw something by hand or in gimp.


You do *not* have to code it, this will exceed the scope of GCi greatly. 

Monika on December 3 2012 23:50 UTC Task Claimed

I would like to work on this task.

Julian Fagir on December 3 2012 23:56 UTC Task Assigned

This task has been assigned to Monika. You have 144 hours to complete this task, good luck!

Radoslaw Kujawa on December 5 2012 17:03 UTC Re: Task assigned

Hi. Do you already have some ideas? We would like to discuss the progress. This task is not as easy as it seems. Please contact us on #netbsd-code channel or irc.freenode.net . 


 

Radoslaw Kujawa on December 6 2012 13:54 UTC Re: Task assigned

Hi, I see that you've visited #netbsd-code when I was absent. You've mentioned that you already have some visual plan for what the browser should look like. We'd like to see it, so we can comment on it and point you in the right direction. 


I have one important suggestion. When thinking about user interface take into account that NetBSD is primarily a text-based operating system. While there are graphical user interfaces available for NetBSD, they are not used where NetBSD is most popular - on server and embedded platforms. So when you are interacting with NetBSD, you mainly use your keyboard (and not mouse). Therefore you should focus on designing an interface that is easy to work with in text mode.


Consider the following: do you need a separate button in user interface for forward/back/print functions if you won't click that button with mouse? Or maybe it should just be a keyboard shortcut? On the other hand, having separate search bar and/or history bar might be useful. 


Also, please take a look at these Wikipedia articles: 



Perhaps it would be much easier to understand if you have installed and tried using NetBSD on a real machine (or in a virtual machine if you don't have any spare computer, we have prebuilt virtual machine images here, these are ready to run in VirtualBox). 


 


If you have any questions don't hesitate to ask.


 

Monika on December 7 2012 06:56 UTC Hi

Thanks for all the links, I've read over them and decided I'm going to revise my plan for the browser into something a little more basic. I had a look at the NetBSD virtual machine image and it's given me some more direction as to what I'm going to do.


Thanks again!

Radoslaw Kujawa on December 9 2012 14:38 UTC Progress?

Hi, you're working on this task for 5 days already. There's not much time left. How is it going?


We can extend the deadline if needed, but you need to upload something you have completed so far.

Monika on December 9 2012 16:39 UTC Progress

I'm about to upload what I've got so far, I'm just finishing an image to accompany it. I'll submit it as soon as I'm finished.

Monika on December 9 2012 17:06 UTC Ready for review

The work on this task is ready to be reviewed.

Julian Fagir on December 9 2012 17:33 UTC Very nice

The result is exactly as expected, or rather: It is exactly different to what I thought how you would do it. I thought about a different design, but it's good to see something different which would reach the same goal.


Thank you! 


 

Julian Fagir on December 9 2012 17:33 UTC Task Closed

Congratulations, this task has been completed successfully.

Julian Fagir on December 9 2012 17:34 UTC Small comment

Just another small comment: There is no such thing as fonts on a terminal interface. The user (or earlier, the hardware) will select the font for the terminal itself.

Julian Fagir on December 9 2012 22:40 UTC Maybe more tasks for you?

You did well with the last two tasks. Maybe this task is also suitable for you (it is about researching which markup you need for documentation): http://www.google-melange.com/gci/task/view/google/gci2012/7983211


If you don't like it, there are other - more general - documentation tasks, which are slightly a different area than the two you did before for us, but I think you would do well on these, too: 



  • http://www.google-melange.com/gci/task/view/google/gci2012/7985209

  • http://www.google-melange.com/gci/task/view/google/gci2012/7988204

  • http://www.google-melange.com/gci/task/view/google/gci2012/7975217

Monika on December 9 2012 23:45 UTC Thanks

Just out of interest, how did you think I would approach it? Thanks though!


Sorry about the fonts, I don't have a lot of experience with terminal interfaces.


I'll have a look at the other documentation tasks and hopefully pick one!

Julian Fagir on December 10 2012 13:20 UTC Rather less-like

I myself would rather use something which is more lynx- or less-like, i.e. just one main screen and buttons for everything, maybe a bottom line with explanations or informations. Your approach was rather mediawiki-like, with a sidebar which consistently shows informations and options. 

Monika on December 12 2012 05:27 UTC Oh

I didn't think of that. Thanks anyway!