search

lxqt / pcmanfm-qt

File manager and desktop icon manager (Qt port of PCManFM and libfm)
https://lxqt-project.org
GNU General Public License v2.0
427 stars 112 forks source link

Add a concise "help" to pcmanfm-qt #550

Closed tsujan closed 3 years ago

tsujan commented 7 years ago
Expected Behavior

pcmanfm-qt has advanced features that aren't shown in the GUI. There should be a "help" item to explain them briefly.

Current Behavior

The "Help" menu has only an "About" item.

Possible Solution

Add a "Help" item to the "Help" menu.

System Information
tsujan commented 6 years ago

I think a help is really needed now.

tsujan commented 6 years ago

There is a problem with a Help doc. Who wants to translate it? Should it be translatable at all? Even a concise Help doc can't be short.

wxl commented 5 years ago

+1

I think this is most needed. pcmanfm-qt is super powerful and has lots of great stuff under the hood that isn't obvious.

Regarding translations, I think it should be translatable. I think we'll find people to translate it, as much as we find people to translate anything else. Sure, they're not just strings, but that doesn't mean we shouldn't leave the option open. I guess what I'm saying is however we implement it, it shouldn't preclude the notion of translation.

One question I have is how do we implement this? Would it be unreasonable to have a second manpage in section 7?

I think perhaps a good start would be at least having something in the wiki. We can easily copy and paste this into whatever format we decide upon when we do decide. That way we can get started now.

And I think that we should use this issue as a catch all any time a new feature is added, so it can be added to the documentation.

tsujan commented 5 years ago

I think perhaps a good start would be at least having something in the wiki

Yes! That's a very good idea.

tsujan commented 5 years ago

Help topics for important but (almost) hidden functionalities:

wxl commented 5 years ago

Manjaro looks like they got a handle on custom actions with lots of practical examples.

tsujan commented 5 years ago

Yes, I'd seen it. Although it's old, it covers the most important part in a way that can't get old. Add to it how to make submenus and how to arrange actions (with level-zero.directory), and it'll be pretty complete.

tsujan commented 5 years ago

The most comprehensible and comprehensive doc about custom actions was the attached page (about old versions of Nautilus), which I'd saved with Firefox's MAF extension. Now, neither MAF nor that page exists!

I think PCMan used it as a guide when implementing custom actions.

Desktop file specification extension - Actions.zip

tsujan commented 4 years ago

To fix a part of the problem, I added a dialog that shows hidden shortcuts, i.e. shortcuts that can't be found in the GUI: https://github.com/lxqt/pcmanfm-qt/pull/1079

stefonarch commented 3 years ago

Some basic things I added time ago in the wiki: https://github.com/lxqt/lxqt/wiki/ConfigGeneral#pcmanfm-qt

But an integrated help is another thing. For translating it's easy now, weblate can handle it (html, txt, yaml or else)

tsujan commented 3 years ago

I've seen many apps with online helps. If we can have a special page for pcmanfm-qt, I'll be motivated to write a help. The good thing about an online help is that we won't need to keep it small. When enough material is added to it, I could add its link to pcmanfm-qt.

stefonarch commented 3 years ago

Online we have the problem of translating, or it hat to be some special page in pcmanfm-qt maybe, which will be seen by weblate. I sometimes happen to have no connection for some day, so Iike more the way screengrab did/does it.

Anyway for now I'll start to put something more in the wiki, based on your list up here.

tsujan commented 3 years ago

Online we have the problem of translating

The situation is a little complicated.

An offline help should be in HTML but would appear like other translatable texts and among them. That's very bad because translating an HTML document is different from translating GUIs. In the case of GUI, if an element is removed, its translation will be ignored automatically but, in this case, nothing will happen by itself when the doc is updated.

I've "solved" this problem in Kvantum by using PDF and not allowing translations. I don't think LXQt would like such a "solution".

Therefore, I think an online help is the correct way to go. It won't be so important if it isn't translated but, if it becomes translatable, it won't be mixed with GUI translations.

In short, this is what I want: not mixing help with GUI with regard to translations.

stefonarch commented 3 years ago

In weblate the help html will have it's own component (as" Menu Entry" for .desktop files) - so it's well distinct. Made just a test with screengrab at https://translate.lxqt-project.org/projects/testing/screengrab-html/ 237 strings but this help is real consistent and way too full.

stefonarch commented 3 years ago

Added also a very first draft, are 25 strings in weblate testing. https://github.com/stefonarch/pcmanfm-qt/blob/docs/docs/en/index.htm

tsujan commented 3 years ago

in weblate the help html will have it's own component

That doesn't solve the problem I mentioned above. IMO, a documentation should to be translated like a book, not like a GUI element. That might be possible with an online help.

Added also a very first draft

Good.

tsujan commented 3 years ago

BTW, Markdown is ideal for writing a help. HTML is too complex, IMHO.

stefonarch commented 3 years ago

BTW, Markdown is ideal for writing a help. HTML is too complex, IMHO.

Sure I wrote it markdown and used an converter ;)

I was looking for a tool where everybody could improve it/edit, I'll paste it here (with some questions) - at least members can edit/change it.

IMO, a documentation should to be translated like a book, not like a GUI element.

Depends how it's written, sure it has to be visualized as a whole too. Doing it in weblate I see that if you add some new explanation this will go in all translations as english immediately, notifying translators about new string. But first we need to have it, then we can see, in the wiki it's good to have but there is a new section needed, it doesn't fit in any now.

stefonarch commented 3 years ago

Draft, some items I didn't know or understand, with question marks

Features

File operations

Search & Filter

Custom actions

Custom actions can be created as '*.desktop files' in '~/.local/share/file-manager/actions/'

Commented example for an custom action to edit text files:

[Desktop Entry]
Type=Action
Icon=accessories-text-editor
#Shown as title
Name=Open as Text
#Same as above, translated
Name[es]=Abrir como texto 

#Specifies for which mimetypes action will be shown
MimeTypes=text/*;application/x-bsh;application/x-sh;text/x-script.sh;application/x-desktop;application/x-shellscript;
Profiles=profile-zero;
[X-Action-Profile profile-zero]
# Application acts on the file
Exec=featherpad %F

how to sort them?

Custom folder icons

From File > Folder Properties or right click on folder > properties: click the icon to change it.

Tab features

Todo

tsujan commented 3 years ago

Good start.

some items I didn't know or understand, with question marks

If you make the page inside LXQt, I'll have write permission and could add them.

stefonarch commented 3 years ago

Done, added the markdown but it looks weblate doesn't supports it. https://github.com/lxqt/pcmanfm-qt/blob/docs/docs/en/index.md

tsujan commented 3 years ago

but it looks weblate doesn't supports it.

Let's have a good doc first. Then, we'll think about its translation.

BTW, I think the html file isn't needed. Markdown is nice with Github and is readable as a text file too.

It might take a long time before the doc is ready but this is a very good idea. Thanks!

tsujan commented 3 years ago

Everything can go to https://github.com/lxqt/pcmanfm-qt/wiki. I just need some time — actually, a lot of time — to make it. Maybe after 0.17.

tsujan commented 3 years ago

And I think "Restrict editing to users in teams with push access only" should be checked in https://github.com/lxqt/pcmanfm-qt/settings

stefonarch commented 3 years ago

So there will be no translations in this case, or still add a Help menu in the menu? The pcman section should be transferred/removed then.

tsujan commented 3 years ago

I assumed GtHub's Wikis were translatable. I haven't made a Wiki yet but if they aren't translatable, I think GitHub is aware of that and will treat it as a bug to fix.

The pcman section should be transferred/removed then.

Later. I think it's good to have each Wiki in the repository of its corresponding app. I got this idea from @yan12125 -- of course, indirectly.

stefonarch commented 3 years ago

Well, wikis are useful - if maintained.

tsujan commented 3 years ago

Well, wikis are useful - if maintained.

Like all other works here, it'll be a team work but, if I start to make the Wiki for pcmanfm-qt -- and I will, sooner or later -- I'll maintain its English (main) version. I may haven't made a Wiki but have written two comprehensive help docs for Kvantum.

Some other components of LXQt need their own Wikis too but pcmanfm-qt has so many hidden features.

wxl commented 3 years ago

I kind of suggested a wiki to begin with but on second thought, I'm wondering if that's the best idea. It's harder for non-team members to contribute to them, there's the issue of translation, and I think worst of all, they exist in a separate repo, so for people that are contributing new or revised features to the actual code, there's no obvious place within the codebase to document those changes. Maybe a simple Markdown file would be a more parsimonious solution?

If we're not going that direction, I'd like to request access to the wiki, as I would like to help with this.

tsujan commented 3 years ago

Maybe a simple Markdown file would be a more parsimonious solution?

I think Wikis are in markdown, like other parts of GitHub.

If we're not going that direction, I'd like to request access to the wiki, as I would like to help with this.

You could be invited to join the team as a member (I'm not familiar with the process yet).

Let me first write a draft, so that we have something to work on. We need to prepare for 0.17 for now.

wxl commented 3 years ago

I simply meant that given the other concerns about the wiki, adding a document of some kind to the normal repo might be a better alternative. I like Markdown and it's the natural language of the wiki anyways, which is the only reason I mentioned that format.

Regarding membership, I'd be interested in joining if that was an option.

tsujan commented 3 years ago

@wxl, I sent you an invitation.

I think you're familiar with how members make changes only after getting the approval of other members but don't hesitate to ask any question you might have.

yan12125 commented 3 years ago

It's harder for non-team members to contribute to them

I think the Wiki can be edited by non-members as "Restrict editing to users in teams with push access only" in repository settings is not checked?

tsujan commented 3 years ago

I think the Wiki can be edited by non-members as...

Yes but do we really want that? IMO, it could result in a mess.

wxl commented 3 years ago

@tsujan got the invited and happily accepted. Thanks, and know that I acknowledge with great power comes great responsibility ;)

Regarding the wiki permission thing, that's one of the exact dilemmas I think we would resolve by having a document in the normal repo. Anything in the normal repo (note here I'm saying normal repo because pcmanfm-qt has a wiki which is in a repo—kind of a GitHub quirk—but it's a repo separate from the repo containing the pcmanfm-qt codebase) can't be pushed to by non-members but non-members certainly can make pull requests against it. There's not really a way to do that with the wiki repo from what I can tell. I agree, though, that I don't think we want a total free for fall.

tsujan commented 3 years ago

@wxl Welcome to LXQt :)

I understand your concern and I agree that a good Wiki should be able to be changed by PRs, and only by PRs.

Maybe, we can have a Markdown doc inside the source and put its link in GitHub's Wiki. If that's not possible, we could update GitHub's Wiki whenever the source doc is changed, or once in a while. It's also possible that GitHub already has a mechanism unknown to us.

0.17 will be released in April and we need to find and fix as many bugs as possible and clean our codes. IMHO, after 0.17, we could focus on the Wiki.

stefonarch commented 3 years ago

@wxl Welcome on board!

By having a document we could add it in weblate, have it translated and also permit source file modification, this would go still over a PR. Unfortunately weblate does'nt handle directly markdown.

wxl commented 3 years ago

@tsujan thanks again and @stefonarch thanks :)

Translations are another concern I had. That's really unfortunate that Markdown isn't accepted by Weblate. What is? Maybe knowing that I can explore the extent of GitHub's wiki capability.

tsujan commented 3 years ago

@wxl Oh, BTW, don't forget to check whether you're watching LXQt repositories (the watch button on the top right). If it's enabled for one repository, I think it should have been enabled for all automatically.

wxl commented 3 years ago

@tsujan I've mostly been watching all activity on all repositories for a while but thanks for the advice :)

stefonarch commented 3 years ago

Weblate handles well html, and personally I like the idea to have the traditional "Help" menu inside the application (atm there are the hidden shortcuts there). I don't think users go to read online docs for their filemanager.

In weblate is a "testing" section (hidden) and I added there th doc branch https://github.com/lxqt/pcmanfm-qt/tree/docs/docs/en/ . Structure is /docs/xy/index.htm and there are tons of converter html > markdown if it's needed. Nice is that it's per string (25 in this draft), so a newly added information will just be shown in english in all translated docs.

wxl commented 3 years ago

I have a personal problem with HTML as it's a really ugly and unreadable markup language, however functional (like XML) it may be. The value with Markdown and similar markup languages is that they're really readable on their own. In that sense, they're way easier for folks to work with. That said, is there any other markup language Weblate will work with that's a little more friendly?

I do like the idea of the help menu, FWIW.

tsujan commented 3 years ago

I don't agree with HTML. IMO, the help should be in Markdown and online. It isn't about how to use the app (that's self-explanatory) but about its hidden features.

tsujan commented 3 years ago

Who can read something like this, let alone translate it?

<code>realloc()</code>?&nbsp;<a class=hover-pop-out href=#renew title="Permalink to this FAQ"><span>¶</span></a>&nbsp;<a class="hover-pop-out js-inline-popup" href=# title="Recommend an improvement to this FAQ" data-tooltip=#popup-suggest data-hasqtip=10><span>Δ</span></a></h3>
<p>If you want to, you can of course use <code>realloc()</code>. However, <code>realloc()</code> is only guaranteed to work on arrays allocated by <code>malloc()</code> (and similar functions) containing objects without user-defined copy constructors. Also, please remember that contrary to naive expectations, <code>realloc()</code> occasionally does copy its argument array.</p>
<p>In C++, a better way of dealing with reallocation is to use a standard library container, such as <code>vector</code>, and let it grow naturally.</p>
<h3 id=new-never-returns-null class="faq-title has-hover-pop-out">Do I need to check for null after <code>p = new Fred()</code>?&nbsp;<a class=hover-pop-out href=#new-never-returns-null title="Permalink to this FAQ"><span>¶</span></a>&nbsp;<a class="hover-pop-out js-inline-popup" href=# title="Recommend an improvement to this FAQ" data-tooltip=#popup-suggest data-hasqtip=11><span>Δ</span></a></h3>

Everyone can read and/or translate this:

# PCManFM-Qt

## Overview

PCManFM-Qt is the Qt port of PCManFM, the file manager of [LXDE](https://lxde.org).

In LXQt sessions it is in addition used to handle the desktop. Nevertheless it 
can be used independently of LXQt as well.
stefonarch commented 3 years ago

I agree with readability of html, I just stumpled upon the fact that weblate "detects" html in the repository (it happened with screengrab). Anyway, in weblate one sees just the string to translate. Supported formats: https://docs.weblate.org/en/latest/formats.html#translation-types-capabilities.

I think online help in different languages (browser setting detecting) is much work and probably impossible in GH, could be done in the website maybe.

BTW we are all reading parsed html here - it's not so bad ;)

wxl commented 3 years ago

@stefonarch maybe I'm missing something but it seems Weblate is based on the Translate Toolkit, which accepts plain text as a format. So maybe without formatting that could work?

yan12125 commented 3 years ago

It's also possible that GitHub already has a mechanism unknown to us.

GitHub can generate a website from a specified folder of a "normal repo", like what it does for https://github.com/lxqt/lxqt.github.io/, and the latter appears to use markdown for posts.

https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

0.17 will be released in April and we need to find and fix as many bugs as possible and clean our codes. IMHO, after 0.17, we could focus on the Wiki.

I need a place for notes about a recently-merged breaking change for qtermwidget. I assume it is quite long and will be referenced often after the next release, so I'd like to place it outside release notes. If there is no concrete decision before the next release, I may place those notes in a folder of qtermwidget main repo and move it around when a decision is made.

stefonarch commented 3 years ago

@stefonarch maybe I'm missing something but it seems Weblate is based on the Translate Toolkit, which accepts plain text as a format. So maybe without formatting that could work?

In the settings I see no plain text to choose. The problem is that any new string (paragraph) or change added should not reset all existing translations, plain text is not suitable for this I think, it would be just one string. But maybe first we should decide

Falkon for example uses local html shown in browser, similar to the (outdated) screengrab docs. So setting up a special website to show html content that can be shown simply locally is a rather complicated way.

I need a place for notes about a recently-merged breaking change for qtermwidget. I assume it is quite long and will be referenced often after the next release, so I'd like to place it outside release notes. If there is no concrete decision before the next release, I may place those notes in a folder of qtermwidget main repo and move it around when a decision is made.

This makes me think that maybe one single well structured wiki is better as many wikis for each component.

tsujan commented 3 years ago

I may place those notes in a folder of...

@yan12125, I thought you wanted to put them into QTerminal's Wiki (which inspired me to enable pcmanfm-qt's Wiki) but do as you see fit.

@stefonarch, let me fist add a draft to GitHub's standard place, namely https://github.com/lxqt/pcmanfm-qt/wiki. I've already started a markdown doc, which be definitely better than nothing, and I'll add it after 0.17. Then, you and @wxl could decide how to move/copy/change/translate it and, of course, I'll participate in discussions.

yan12125 commented 3 years ago

I thought you wanted to put them into QTerminal's Wiki (which inspired me to enable pcmanfm-qt's Wiki) but do as you see fit.

That was indeed my initial intent. But after reading discussions here, I don't think the Wiki is a good idea anymore. Wiki's biggest issue to me is either that there is no good way to contribute or there is no review before changes.