Temporary structured pdf of XLSFORM tutorial

(Souirji Abdelghani) #1

Hi all,

There is a very good tutorial on XLSFORM design at http://xlsform.org/. Unfortunately, it is not available in pdf format for offline study. I have therefore prepared a structured (with table of contents) pdf of this tutorial.
I am uploading it here in case it can be helpful for some of the forum users.XLSFORM tutorial_edSouirji.pdf (956.1 KB).
Naturally, the authors of the original work http://xlsform.org/ deserve all the credit.

(Narendra) #2

You nailed it man, Salute you.
All beginners will use this. You work is also appreciative along with authors.

(Yaw Anokwa) #3

@adammichaelwood Do you know if it's possible to automatically generate some sort of PDF of the Docs website?

(Souirji Abdelghani) #4

Hi @yanokwa,
It is possible to produce a pdf from most web pages in Mozilla Firefox. While the web page is opened, click File/Ok wait for the pdf to be prepared then, in the windows browser that opens, give it a name and choose the folder to save it.

I have attached what you'll get from http://xlsform.org/. What is an XLSForm_DirectPrintFromWebsite.pdf (645.4 KB).
As you can see the web links aren't functional and there's no active table of contents.

Wikipedia has an article on exporting articles as pdf files at https://www.mediawiki.org/wiki/Reading/Web/PDF_Functionality. Perhaps you can find there some clues about your pertinent question.

(Adam) #5

We can build a PDF of the docs in Sphinx.

It could be made a part of the CircleCI build process and simply made available.

(Souirji Abdelghani) #6

With Sphinx, one can also build epubs. That's handy for use in ebook readers!

(Souirji Abdelghani) #7

Hi @yanokwa,

I'm sorry I didn't realize you're asking about possible tools to be made available for use in ODK's Docs website. Does this website already exist and if yes, can you kindly provide a link?

(Ronald Munjoma) #8

Hi @Souirji_Abdelghani

Yes, it does exist. http://docs.opendatakit.org/

(Souirji Abdelghani) #9

Hi @Ronald_Munjoma,

Thank you so much; how comes I haven't seen this before???
I have just had a first quick look. This docs website is very well-designed and useful. Thumbs up to the authors.

And yes it would be great to add pdf and epub export functionality.

(Ronald Munjoma) #10

Hi @Souirji_Abdelghani

Looks like you missed the memo!

(Hélène Martin) #11

@Souirji_Abdelghani I'm so happy to hear you're enjoying the new docs! Thanks to @adammichaelwood for leading that effort.

If you have suggestions on how we can make sure this kind of information goes out more effectively, please share. Sorry you didn't see it before!

Export functions would be absolutely fantastic.

(Souirji Abdelghani) #12

Hi @Ronald_Munjoma,

I did, because Documentation is buried in the Development category which is mostly visited by people involved in software development activities; a (very useful) minority in this forum.

I kindly propose that Documentation be a category in its own right because its scope goes far beyond software development; it's the first place to visit for all ODK users! Upgrading Documentation to a full category status will give it more visibility.

And yes @LN, Many thumbs up to @adammichaelwood!

(Adam) #13

Thanks for all the kind words and support. We've been working hard to transfer docs, rewrite docs, and write new docs. We still have a lot of work to do, but it's coming along -- thanks especially to the Outreachy applicants, who have really sped up the work over the last month or so.

I have opened an issue to talk about PDF export. I have some concerns about doing so -- we don't want to encourage the proliferation of outdated documentation -- but it is definitely a possibility. EPUB as well... doable, but I do wonder about the potential problems.

Another docs deployment possibility -- We could add the docs in the Collect app.
This has been discussed briefly here: https://github.com/opendatakit/collect/issues/1398

If we're interested in an offline copy, this would be my highest preference, as we could make sure it updated when people were online with their devices.

(Souirji Abdelghani) #14

Hi @adammichaelwood,

Thanks for your great work and thoughtful remarks. I do understand your concerns about people using outdated PDF and ePUB docs. However, from experience I worry even more about people in the developing world not being able to stay online to read and work with lengthy documents. Indeed, Internet connections are often unreliable and very costly.

I would suggest to use the method of QGIS documentation; you can either read the documents (user guide or training manual) online as HTML file or download a PDF file which always includes the date (of the download) on the front page. This way it's the user's business to get regularly updated.

(Hélène Martin) #15

Great suggestions, @Souirji_Abdelghani.

I see your point on this but I wonder whether creating a new category is the right approach. I think what's missing is a link to the docs themselves from the main ODK website so that users easily find them. The reason that isn't there yet is because there are still some key resources missing from docs. As soon as they're up, links will be updated.

This documentation forum category is for discussion about developing the docs, not really for users to find the docs.

I propose that we work to get the docs site to a place where it can be linked from the main ODK website and get redirects up for each documentation page on the website AND get an announcement post out soon highlighting the existence of the doc. Announcement posts are emailed to all forum subscribers so I think that will help give them visibility. How does that sound, @Souirji_Abdelghani?

(Souirji Abdelghani) #16

Hi @LN,

Thank you for your thoughtful comments. I agree with your comments and proposed solution for forum users to easily locate and access ODK documentation.

(Hélène Martin) #17

2 posts were split to a new topic: Sub choices not available on device

(Yaw Anokwa) #18

Thanks to @ankita240796's great work. We now automatically generate a PDF of the docs. You can find the link at the bottom of every page of the docs.

Try it out today and if you have problems with the PDF, please file an issue at https://github.com/opendatakit/docs/issues

(Narendra) #19

Great work @ankita240796, keep this spirit.


(Ankita Saxena) #20

Thank you @yanokwa and @iamnarendrasingh :slight_smile: