docs: remove texinfo #168
docs: remove texinfo #168
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #168 +/- ##
=======================================
Coverage 96.85% 96.85%
=======================================
Files 18 18
Lines 795 795
=======================================
Hits 770 770
Misses 25 25 🚀 New features to boost your workflow:
|
|
close #167 |
|
@sbillinge It's ready for review. |
sbillinge
left a comment
sbillinge
left a comment
There was a problem hiding this comment.
Thanks @ycexiao for this. To make sure everything is working and make it easier to review, it might make sense to put screenshots of the previous manual and how it looks in the new form. Then we can be sure that everything is there and nothing is lost. If the manual is long, we could just do the top of each section or something like that?
| USING PDFmorph | ||
| ------------------------------------------------------------------------ | ||
|
|
||
| For detailed instructions and full tutorial, consult the user manual |
There was a problem hiding this comment.
I think we still would like a link to the manual. So this shouldn't be deleted but modified to point to where the new manual will be.
If we don't quite know that yet, please create an issue to fix that later, then we can resolve this conversation. But if possible, fix it.
doc/source/quickstart.rst
Outdated
| Welcome! This will be a quick tutorial to accquaint users with PDFmorph | ||
| and some of what it can do. For a more detailed tutorial, check out | ||
| our :download:`user manual <../manual/pdfmorph.pdf>`. | ||
| and some of what it can do. |
There was a problem hiding this comment.
see above, I think we need a link to the new manual here.
|
New, section beginning Old, section beginning |
|
@sbillinge Please review this. Old pdfmorph.pdf is reserved in the |
sbillinge
left a comment
sbillinge
left a comment
There was a problem hiding this comment.
please see my latest inline comments
| that are not PDFs, it has not been extensively tested beyond the PDF. | ||
|
|
||
| To get started, please visit the :ref:`quick_start`. | ||
| To get started, please download our :download:`user manual <pdfmorph.pdf>` |
There was a problem hiding this comment.
I think the pdf version won't exist any more shortly, right? Just the version in the online docs. Isn't this the goal of your project?
There was a problem hiding this comment.
Yes there will only be the online version. I think I misunderstood your previous comment, which said there should be a link to the manual. So I recovered the older version of pdf.
Now I am a little unsure, do we need the pdf manual built by rst? Because the information already exists and is better rendered in the online documents. Or just leave the link to the online documents.
There was a problem hiding this comment.
As guidance, maybe remember your goal and your target audience. It is a new user of PDFmorph. They have read the introduction and are excited to use it. What to do next? I think that person might like to given some possible "next steps" to get started. So if they see something like:
To get started, please visit the :ref:quick_start. I think it could be helpful, if when they click it and go there, there are nice and clear steps about how to get started. Did you test that "flow" as if you were a new user and see if you think it is easy to follow and makes sense? That is the task here that we are looking for.
Also, because we want to remove the PDF/texinfo manual, we want to double check that there is nothing in there that is NOT in the rst version of the manual that we might lose and don't want to lose. That can be on another PR.
Have you used PDFmorph? Do you know what it is for and how it works? This is probably important or you won't be able to do this job well.
There was a problem hiding this comment.
Thanks for instructions. I see that the job here is more than just removing the files and replacing with the new ones. I will get into the repo itself and gain more insights about learning and using it through the old and new manuals.
| Welcome! This will be a quick tutorial to accquaint users with PDFmorph | ||
| and some of what it can do. | ||
| and some of what it can do. For a more detailed tutorial, check out | ||
| our :download:`user manual <pdfmorph.pdf>`. |
There was a problem hiding this comment.
please see above. no more texinfo so no more PDF version of the manual? Do we need to talk again to make sure our goals are aligned?
|
@ycexiao I wonder if we want to create a new clean PR for this work now that it is better understood. What do you think? On another note, I see a lot of image files being deleted. Is this because they exist in another place and are replaced, or are these images that are not used in any manual? |
Sure. And I can follow the correct concept working on this issue in the new PR, too. About the images.The situation is that the last several sections are removed. According to Andrew, these sections are focused on the theory derivation, which are little off topic and they can also be found in cited papers. I think in the new manuals we should leave these complex theories aside and just provide clear citation to these papers. Also considering the time need to configure the .rst to properly render math equations, these sections are removed and images are deleted. |
sounds good. Please make sure to add text explaining where people can find that information with citations to the papers. |
2 participants
closes #167