[Vorschlag] 98_help.pm zur Anzeige modulspezifischer Doku

betateilchen · 16 Februar 2015, 18:44:11

Angeregt durch diese im Rahmen einer ganz anderen Diskussion aufgeworfene berechtigte Bemerkung:

Zitat von: AitschPi am 15 Februar 2015, 18:45:01
Die Befehlsreferenz in aktueller Form Mistbauch recht träge, denn da ist in den Jahren jetzt ziemlich viel hinzu gekommen.
...
Dann muss nicht immer alles komplett auf leistungsschwachen Telefonboxen oder Einplatinenrechnern laden, nur um für ein Modul etwas nachzusehen.

habe ich mich hingesetzt und ein CommandModul 98_commandref.pm zusammengeschraubt, mit dem man die Doku für ein einzelnes Modul aufrufen kann, die dann im Frontend angezeigt wird.

Damit der html-Inhalt im content-<div> des Frontends angezeigt wird, fiel mir kein anderer Weg ein, als diese zwei Zeilen in die 01_FHEMWEB.pm einzufügen:

Code Auswählen


Index: 01_FHEMWEB.pm
===================================================================
--- 01_FHEMWEB.pm	(revision 8009)
+++ 01_FHEMWEB.pm	(working copy)
@@ -761,6 +761,7 @@
     $FW_room = "";
 
     if( $FW_cmdret !~ m/<html>.*<\/html>/ ) {
+      if( $FW_cmdret !~ s/commandreftext// ) {
       $FW_cmdret = FW_htmlEscape($FW_cmdret);
 
       my @lines = split( /\n/, $FW_cmdret ); # Adding links
@@ -776,6 +777,7 @@
 
       $FW_cmdret =~ s/:\S+//g if($FW_cmdret =~ m/unknown.*choose one of/i);
       $FW_cmdret = "<pre>$FW_cmdret</pre>" if($FW_cmdret =~ m/\n/);
+      }
     }
 
     FW_pO "<div id=\"content\">

Ich stelle das hier einfach als ersten Entwurf zur Diskussion. Falls jemand bessere Vorschläge hat, immer her damit.

Code Auswählen

commandref frm_lcd

liefert beispielsweis als Ergebnis (ich hatte eine möglichst "kleine" Doku gesucht):

(http://up.picr.de/21018734ph.png)

justme1968 · 16 Februar 2015, 19:24:33

genau das wollte ich auch schon einbauen

um html anzuzeigen musst du nur ein <html> tag um die ausgabe rum machen. d.h. die zeile 47 so ändern

Code Auswählen

return "<html>$output</html>";.

genau für die möglichkeit aus einem kommando direkt html zurück geben zu können hatte ich die m/<html>.*<\/html>/ prüfung ja eingebaut.

ich fände es schön wenn diese funktionalität in das normale help kommando eingebaut wird. das ist kürzer zu tippen und vermutlich sogar etwas das die meisten probieren.

gruss
andre

betateilchen · 16 Februar 2015, 19:30:16

Das hatte ich probiert - aber das hat nicht funktioniert.

EDIT: Wieso funktioniert das jetzt? Ich hatte vorhin fast eine halbe Stunde daran rumgebastelt, das mit <html> zum Laufen zu bringen...

Ich schau mir mal an, das in help zu integrieren.

justme1968 · 16 Februar 2015, 19:36:00

das habe ich gerade hier probiert und es geht... sowohl mit safari als auch mit chrome.

und noch ein vorschlag. wenn man die rückgabe im telnet fall ein klein wenig aufbereitet ist es auch per telnet halbwegs benutzbar:

Code Auswählen

if( $cl 
    && $cl->{TYPE} eq 'telnet' ) { 
   $output =~ s/<br>/\n/g;
   $output =~ s/<\/a>//g;
   $output =~ s/<a.*>//g;
   $output =~ s/<ul>/\n/g;
   $output =~ s/<li>/-/g;
   $output =~ s/<\/li>/\n/g;
   $output =~ s/<\/ul>/\n/g;

   return $output;
} 

return "<html>$output</html>";

betateilchen · 16 Februar 2015, 20:25:55

Zum Testen in der fhem.pl:

Code Auswählen


sub
CommandHelp($$)
{
  my ($cl, $param) = @_;

  if($param) {
     return getCommandref($cl,$param);  
  } else {

  my $str = "\n" .
            "Possible commands:\n\n" .
            "Command   Parameter                 Description\n" .
	    "-----------------------------------------------\n";

  for my $cmd (sort keys %cmds) {
    next if(!$cmds{$cmd}{Hlp});
    next if($cl && $cmds{$cmd}{ClientFilter} &&
            $cl->{TYPE} !~ m/$cmds{$cmd}{ClientFilter}/);
    my @a = split(",", $cmds{$cmd}{Hlp}, 2);
    $str .= sprintf("%-9s %-25s %s\n", $cmd, $a[0], $a[1]);
  }

  return $str;
  }
}

sub getCommandref {
	my ($cl,$mod) = @_;
    return "Usage: commandref <moduleName>" unless $mod;
    $mod = lc($mod);
    my @tags = ();
	my %mods;
	my @modDir = ("FHEM");
	foreach my $modDir (@modDir) {
	  opendir(DH, $modDir) || die "Cant open $modDir: $!\n";
	  while(my $l = readdir DH) {
		next if($l !~ m/^\d\d_.*\.pm$/);
		my $of = $l;
		$l =~ s/.pm$//;
		$l =~ s/^[0-9][0-9]_//;
		$mods{lc($l)} = "$modDir/$of";
	  }
	}
	return "Module $mod not found" unless defined($mods{$mod});
	my $output = "";
	my $skip = 1;
	my ($err,@text) = FileRead({FileName => $mods{$mod}, ForceType => 'file'});
    return $err if $err;
    foreach my $l (@text) {
	  if($l =~ m/^=begin html$/) {
		$skip = 0;
	  } elsif($l =~ m/^=end html$/) {
		$skip = 1;
	  } elsif(!$skip) {
		$output .= $l;
	  }
	}

   if( $cl  && $cl->{TYPE} eq 'telnet' ) { 
     $output =~ s/<br>/\n/g;
     $output =~ s/<br\/>/\n/g;
     $output =~ s/<\/a>//g;
     $output =~ s/<a.*>//g;
     $output =~ s/<ul>/\n/g;
     $output =~ s/<\/ul>/\n/g;
     $output =~ s/<li>/-/g;
     $output =~ s/<\/li>/\n/g;
     $output =~ s/<code>//g;
     $output =~ s/<\/code>//g;
     $output =~ s/&lt;/</g;
     $output =~ s/&gt;/>/g;
     $output =~ s/<[bui]>/\ /g;
     $output =~ s/<\/[bui]>/\ /g;
     $output =~ s/\ \ +/\ /g;
     $output =~ s/\t+/ /g;
     $output =~ s/\n\n/\n/g;
     return $output;
  } 
  return "<html>$output</html>";
}

Markus Bloch · 16 Februar 2015, 20:36:27

finde ich super. Daumen hoch dafür.

betateilchen · 17 Februar 2015, 08:06:29

Allerdings würde ich dafür plädieren, die CommandHelp dann komplett aus der fhem.pl auszulagern. Zum einen, um Rudi und die fhem.pl zu "entlasten" und zum anderen aus Gründen der Wartbarkeit der Hilfefunktion generell.

Einschränkungen sehe ich dabei nur eine: Die Eingabe von "?" zum Aufruf der Hilfe würde vermutlich nicht mehr funktionieren. Man könnte aber sicher einen Hinweis ausgeben, "help" zu benutzen oder ähnliches.

Eine Moduldatei für die CommandHelp habe ich hier bereits fertig.

rudolfkoenig · 17 Februar 2015, 16:01:30

ZitatEine Moduldatei für die CommandHelp habe ich hier bereits fertig.

Wo denn?

ZitatDie Eingabe von "?" zum Aufruf der Hilfe würde vermutlich nicht mehr funktionieren.

Vermutlich kann man das mit ReplacedBy (analog zu updatefhem) auch loesen.

betateilchen · 17 Februar 2015, 18:46:27

Ich hab das Modul jetzt nochmal "schöngemacht" und auch eine Doku ergänzt.

(http://up.picr.de/21028931rs.png)

Das Modul kann ich bei Bedarf jederzeit einchecken, vorausgesetzt, SVN ist irgendwann wieder bereit, commits entgegenzunehmen. Es klemmt grade mal wieder.

In der fhem.pl gibt es (wenn ich mich recht erinnere) vier Stellen, an denen Bezug auf CommandHelp() genommen wird.

rudolfkoenig · 18 Februar 2015, 18:41:59

- 98_help.pm aus contrib nach FHEM geschoben.
- help / CommandHelp aus fhem.pl entfernt
- ? verweist auf help per ReplacedBy
- Attribut language fuer global eingefuegt (jaja, Pandora und so).
- help Abschnitte aus commandref_frame*.html entfernt
- deutsche Uebersetzung in 98_help.pm hinzugefuegt.
- "Device Specific help" in der Detail-Ansicht wird beim Laden von fhemweb.js durch ein Aufruf von "help <modulname>" via XHR ersetzt. Vorteile: Spuerbar schneller und die Hilfe wird auf der gleichen Seite angezeigt. Nachteil: die HTML-Links funktionieren (noch?) nicht.

Bemerkungen:
- help im telnet ist noch ziemlich unverstaendlich, siehe "help at" oder "help notify".
- man koennte einige Abschnitte aus doc/commandref.html anzeigen, wie global, command, devspec, attributes und perl, auch weil man in FHEMWEB im global-Detailansicht "help global" aufgerufen wird. Falls deswegen commandref_frame.html angepasst werden muss, dann bitte Bescheid geben.

Es waer mir lieber, wenn du (betateilchen) das Modul uebernimmst.
Falls dir das nicht passt, dann werde ich der Maintainer.

betateilchen · 18 Februar 2015, 19:17:49

Zitat von: rudolfkoenig am 18 Februar 2015, 18:41:59
Es waer mir lieber, wenn du (betateilchen) das Modul uebernimmst.
Falls dir das nicht passt, dann werde ich der Maintainer.

Doch, passt schon. Ich kümmere mich drum, auch um Deine Anmerkungen oben.

betateilchen · 18 Februar 2015, 20:39:27

"help" kann jetzt auch deutsch. Nach dem Modulnamen ein "de" als Parameter angeben.

justme1968 · 18 Februar 2015, 22:36:08

ich glaube rudis idee war das language attribut zu verwenden um die default sprach zu bestimmen. dann müsste man de oder en nur noch angeben wenn man gerade nicht den default möchte.

für die deutsche version wäre es glaube ich noch gut die &uml tags zu ersetzten.

vielleicht könnte man optional auch das HTML::FormatText modul für die telnet version verwenden wenn es installiert ist.
das formatiert die listen ziemlich gut.

betateilchen · 18 Februar 2015, 22:48:32

wer setzt denn schon das language Attribut?
en muss man nicht angeben, das wird verwendet, wenn nicht explizit de angegeben wird
die Umlautersetzung kommt noch

Solange nicht jedes Modul mehrsprachige Doku liefert, macht eine automatische Sprachfindung für mich keinen Sinn.
Ebenso dürfte sich der Kreis der Anwender, die per telnet arbeiten und dabei dann doch noch die modulspezifische Hilfe brauchen, ziemlich in Grenzen halten.

justme1968 · 18 Februar 2015, 22:55:23

Zitatwer setzt denn schon das language Attribut?

vermutlich noch niemand. das hat rudi wie oben steht gerade erst eingebaut. in zukunft vermute ich aber einige. zumindest wenn es eine sinnvolle verwendung dafür gibt. das help modul wäre genau so eine...

wie kommst du auf automatisch?

aber da du es ansprichst: wenn es in der deutschen version den 'Leider keine deutsche Dokumentation vorhanden. Die englische Version gibt es hier...' link gibt könnte man automatisch auf die englische umschalten.