 Hello all let us continue with our sessions so far we have seen how to work with git repositories how to debug android efficiently these are small session we will see how to write a markup document and export it to pdf and html so far whatever documents you receive these 3 pdf they have been written in rst only so the entire session handouts which you have followed since morning they all have written in rst format then exported to pdf so you already know the importance of documentation as we discussed in the morning that before writing any meaningful code you should first write a document of it a read me of it so many many companies in fact they invest much more in preparing documentation then actually writing a code because that that actually creates a ecosystem of confidence the user get user feel confident that the product which is using the application which is using is of some value to him is not getting lost somewhere so in this session we will see okay let us start with wide documentation of course almost all the projects whether it is microsoft project or google project any project they have excellent online and offline documentation you probably know that in windows have their help open to have their help in when you press F1 you get system help command line you have man pages hyphen hyphen help so people do respect the code people do respect the developer when he provides a good manual with the application so we will start directly with well-known tools already available for writing documentation which many people use so I guess most of people are accustomed with microsoft office or open office you can see on GNU linux environment both of these sorts will allow user to export to pdf and html format but you cannot make a good css based document with these office tools second one is latech which is very very popular and very good typesetting language though it is it has a steep learning curve but once you get used to it you really you would you would not try anything else other than latech so the debugging latech documents might be little tricky but of course once you get used to latech is best of among all these tools even rht also wiki language you already know wiki text if you have ever edited a wiki page wiki pdf page or wiki document based any websites so they have their own markup though you can export to html I have not heard of pdf export there we will concentrate on restructured text which appear in 2002 it is a again a lightweight markup language which is now very popular among open source developers even in closed source developers also so you can do lot more things which you have not heard of before I will demonstrate few like suppose you want to write your phd thesis you can write in rst it will create a beautiful two column format with all embedded images etc etc you can use it for that you can write man pages manual pages you can write system help you can write online html based help you can write anything with restructured text restructured text is nothing but a simple markups which when rendered produces the beautiful html or pdf so far this document this very document what you are looking now is converted from restructured text rst dot rst file like we have seen read me dot rst and it has been converted to pdf so there is a command in Linux and probably it will work in windows also because the python based command so rst to pdf is the command which we will see just right away so by that you can convert it to pdf that is it that is simple okay so next one is markup markdown language actually I think I did some indentation mismatch in rst rst is very much indentation specific language markup language so I think there is some indentation mismatch between restructured text rst and markdown md because the number should be 4 and 5 we will fix it to show you how it works so the number should be 3 4 5 so markdown it says 1 it should not be 1 it should be 5 okay we will come to that it is good that we have a bug in our document so there is no need of any tutorial as I as you know see this is a tool a simple tool like using a gmail to edit your to compose your mail what you do you use sometimes code to code tag sometime you make it bold sometime you use different tags means you use a mouse cursor to click on particular tag which enables it to enable that tag for you which works in the background in the restructured text same thing happens but instead of clicking something on a plain text file no document format no doc no oddity no such format plain dot txt form or dot rst form you write the document you just convert it and you are ready to go we will see in just in this next topic so this is a ready to paste version of a document which does not make any sense this is this does not make to this does not make to make any sense because in this small document I want to show you as many rst tags as possible when you build an pdf you will know that which tag converted to which one so as you can see what I will do is I will just copy this to my text editor that is it I will copy in fact I have already copied it I need to just go to that document so vi temp dot rst so temp dot rst contains this document so this is the same content which we have just copied from this document what it says version control with double dotted lines what if I miss one underline one equals to so when you compile this how do you compile exit rst to pdf it is a command temp dot rst so this is the command so we already know that there is a document in a rst format in which we deliberately made a mistake let us see how rst treat dance so it says warning title underline is too small too short okay but it converted fine so to view that document we can simply do evince evince is a pdf viewer temp dot pdf so this is the newly created temp dot pdf so the text which we have written in temp dot rst is converted into this beautiful pdf format so what was the text let us compare the text now let me open a new terminal vi temp dot rst so you can see that version control of course with warning it compiled so this is the heading it says content git version control with simple hello world project I have taken the similar document same document of git version control and stripped down to one page format though totally meaningless but just to show how tags are arranged here instead of making breaking page here I rather decided to make it continue so we compare with this it says dot dot space contents colon colon this is a syntax for directives the directives means these are the plugins kind of plugins so one can write a rst document a beautiful simple rst document with these plugins which will allow him to write many things means see the contents this first line will convert all the header tags means all the headlines like this is a headline means this is a topic topic subtopics it will compile every topic and subtopic into bold letters headings so see you can see this is the git version control with simple hello world project that 1.1 is pushing a project to server takes automatically so where is our 1.1 we have not mentioned any 1.1 here just by mentioning tilde underline as underline we convey to rst that this is a subheading this is not the main heading this is a subheading like you can see the git version control is with dotted lines so it has been converted into heading and 1 next to it has the tilde which is converted into subheading again if you give other headlines like this then it will convert into sub subheading okay so how this text box appear in this format so all you have to do is use indentation see hash dot will be converted into point number 1 so hash will be auto numbered so if you have hash dot hash dot hash dot 3 points it will be 1 2 3 okay so create a directory say hello world hello world will be in italics now in your home this will be turned into also italics directory and cd then with double call ins you are telling rst that okay whatever the topic comes next it will be shifted means it will be a text box it will be a message box kind of then mkdir hello world if I make this here as you can see the syntax also changes means the highlight also changes and if I save it and compile it means convert it rst to pdf temp dot rst it says again a warning literal block expected none found because we have changed the literal block it expects a indentation we remove that indentation so let us see how our created directly say hello world in our home directory and cd this make directory did not come in the literal block it disappeared it just came as a plain text we do not want this so let move it back so that so I have provided one tab space so it will now move to a literal block this way save and exit rst to pdf one warning still there because we have omitted one equal to sign from that underline so now the all literal block is back so all you have to do is give double call ins double call ins after any statement after that whatever you write in a indentation form it will be turned into a literal block see it seems little complex now but when you when you actually see the documentation and do side by side right it is very very easy I wrote all three documents in probably two days and that too I was not continuously working on the documentation similarly these stars will turn into bullets so this star means it will be a bullet number a bullet one can access code from anywhere easy to add remove if I change this star to hash so now it will become numbered previously it was bullets if you see here previously it was it was bullets now I change the star to hash and if I compile back now it becomes one two instead of bullets you follow fine you can add images also it is very simple to add images I have added plenty of them how to add an image very simple if you want to add an image in line like if you remember this document we have a git logos here okay assuming git is already installed on your machine so what I did I inserted a logo in between a text is also possible how just use dot dot directive these syntaxes are there in one manual page I have provided a link below you have to just follow the manual page whenever you need a certain command this logo dot png is the mark means text this is replaced by data slash logo dot png and the width of the image is scaled down to 30% so on and so forth similarly if you want to add a regular image all you have to do is dot dot space image colon colon see this syntax is constant means dot dot space any directive name there are tons of directives like you can add image you can add warnings you can add help you can add many things means whatever which communicates to user there are some directives available to that you do not have to remember any of these tags just search in the manual it will be there copy paste that's it so this is a code block directive code block directive will make your code look as a format your code at this line numbers will add line numbers to your code so you can see as we have changed our thing so it didn't appear what I will do is let's fix this let me do it again why not we fix this also so it will convert neatly and there is a literal block here as decided collaborator will follow content let's remove that literal block so all you need is rst2pdf command which you can download with oven 2 app get install rst2pdf or download the source which the link I have already provided about so this is a sample screenshot of the output what you will receive there directives we already discussed so dot dot image colon colon logo dot png is a directive so these are the similar to attributes to any class so these are your options available with this particular directive indentation is important as you have just seen with improper indentation we lost our formatting so indentation is important and you should stick to one kind of indentation suppose you are using four spaces for a tab you should stick with four spaces only should not use four spaces for one page each space for next page it won't work so the next part is converting rst files into html you can directly convert rst to html there is a command rst2 html which just converts this temp dot rst to say one dot html with some this literal block error no problem we can open this html in our browser and we can go through but there is a better way of converting into html that's what I want to convey instead of converting into plain html which of course will have some css we have a package known as sphinx python sphinx which is which is very very popular and very easy to work with all you have to do is install python sphinx from here so they have to get installed python sphinx or you can download these are python package you can download from pypy python server and you can easily install it how to start sphinx quick start you have to do what I will do I will these are directory in which I have created all my files from yesterday adb and busybox dot rst git intro dot rst rst hyphen pdf sphinx dot rst all this source files are available in my github account which you have already know 3 can github.com slash 3 can put now so you can download this rst files if you want to refer it further so what I want to do is I want to convert this rst files into sphinx sphinx documentation sphinx is a preformatted well suited document representation form specially written for python but you can use it for anything so it will ask you step of yes or not no type of questions which almost you have to say yes for all enter enter enter like that I have already done this yesterday no need of doing it again all I have to do is open index dot rst which will when you do yes yes to all those questions it will create a index dot rst in your present working directory in this index dot rst I have mentioned my three files git hyphen intro adb and busybox rst hyphen pdf sphinx without the extension if you see I have not mentioned any extension here so this when I compile make html it will create html files within say 15 to 20 seconds not more than that and it will be available in slash underscore build html so all my files are available here if I want to see how my rst files look as html you can open it like google chrome I use chrome frequently so google chrome where is my index dot html index dot html so when I hit enter so it says welcome to android workshop IIT Bombay documentation so this is very easy to browse you can have you have quick search here you have topics listed everything is in line version control first topic sub topics also listed advanced android debugging all of them are available restructured text everything is there let us see how a busybox look that is it so it has been converted into html in no time so what I have done I have written all my documents in plain text format then depending upon my need I converted into pdf and provided to you for further study if I want to put this online which I did yesterday night you can go through this from anywhere just go to it dot itv dot repo dot html so I uploaded this on this url yesterday night so that I can show you during the session so this link you want to access you can access from your own local machine let me so this is the url you can just visit this url and you can find out how the pdf document which you have in your machine looks when you convert it into html so the same rst file has been converted into html so you go to version control you have complete details as you would have written in html why version control everything is linked your literal boxes come properly you have line numbers as we have mentioned call and line numbers for directive for me very easy and straight forward means most of the documents I want to show one more link akashlabs.org slash docs so this is the documentation which we made for our project so we made akash programming lab which essentially provides you silabs cc plus plus and python programming programming tools on akash tablet so we have written complete offline as well as online documentation for developer as well as user also so it took us yes lot of time but it is worth making this documentation you can see this document it is very simple user manual let us see user manual how it looks how to use it so this is how our application looks so this is text area console output etc etc so we have written it in plain rst same as like we have written for this thing you want to see source you can see source show source it will directly print your rst source file on your browser that simple we have created a document for linux on akash also docs so we have ported gnu linux on akash tablet which can essentially done from micro hd card so it is good to have a complete online and offline document for this process what we have done because probably this is very unique moment for us that complete gnu linux is working on akash so we decided to make full document for that that how to set up everything you need how to compile kernel how to compile hd card etc this is all information is available on our github account andro portal github.com slash andro portal why I am why I am showing all this because see means it is very easy for us to generate a very professional quality documentation using simple plain text in rst format all you know do is just go through these links this doc utils.sourceforge.net is the official hosting for this package you can find quickly reference restructured text etc and that is almost everything for this session if you have any questions quick questions you can just ask me someone has requested me to show how to install how to install application using adb so let me do it so you can see there is an fdroid.apk is there and my android debugging is already on and I can show you so our debug connection is back so I am just replying to question that adb install apk name say suppose fdroid.apk will install this apk on my tablet suppose this apk is already installed and I want to install it again without losing its data I will use hyphen r flag success so same thing you can do with your emulator also so you are just when you connect to your emulator just do adb devices to verify whether your emulator is connected or not it will show that emulator is connected then you can just do adb install whatever application you want one topic I mentioned before like license so but I did not cover license I hope it is not that difficult for you to find out how a license look and what exactly licenses are I will give you a brief very brief introduction for license so I basically followed this web page if you can see so I agree with this data that is why I am showing it so I thought it is not relevant to make another document for just license it is very simple topic mostly you should do with open source license of course when we see open source the first license come in our mind is GNU GPL so GNU is the main project which says that any license any source code when you release it should be it should give freedom to user to modify to redistribute and to respect the user's name means suppose I have downloaded some GNU license GNU application if I want to redistribute or modify the source code I should modify on these these terms that means I should mention the name of the author original author then I should redistribute etc this is very simple to understand all you need to understand is what kind of freedom you want to give to your users when you tell them any tell when you choose some license so most commonly used licenses are GNU GPL version 2 because version 3 have some differences which Linus Torvalds does not agree so version 2 is most popularly used Apache license is also very open license you can do whatever with code that you want you can even close yours for the branches also suppose in GNU license GNU GPL license you are forced to release source in open only you have you are forced to release open source only later modifications but consider this BHD license it does not force you to do that suppose you have like if you consider Macintosh they they also took source code from UNIX then they then they modified their version of operating system and they made it close source they based on BHD license so BHD license give you freedom to user that you download my source you want to release that open source if you do not want to we do not have any problem so BHD license give you freedom of course many open source people do not agree with BHD license so by default if you want to invoke any license in your project that you should do of course you should include a GNU GPL version 2 license or any license whatever you study better you can use so that is all about this session before closing this session I want to convey to you people that if you have not already switched to GNU Linux it is the right time to switch because there are many open source projects there are lot of demand for open source developers there is firefox os known as gecko there is tizen project which is again an open source project mobile platform and tablet platform there is ubuntu for tablet ubuntu for phone of course android is there so almost all major computing devices almost 75 to 80 percent of web servers version some variant of linux operating system so the future belongs to linux based developers so you can try both means you can have windows as well and for development you should of course try with linux of course with android development it is easy for easy to develop android application on linux platform rather than windows platform thank you all I hope you have enjoyed these sessions