Hilfe für Programme (plattformunabhängig)

Für Fragen zur Programmiersprache auf welcher Lazarus aufbaut
Antworten
Ich934
Lazarusforum e. V.
Beiträge: 316
Registriert: So 5. Mai 2019, 16:52
OS, Lazarus, FPC: ArchLinux und Windows mit FPCUPdeluxe (L: 2.0.X, FPC 3.2.0)
CPU-Target: x86_64, i386
Wohnort: Bayreuth

Hilfe für Programme (plattformunabhängig)

Beitrag von Ich934 »

Hallo zusammen,

wie löst ihr das mit der Hilfe für ein Programm? Ich habe hier das Problem, dass ich diese ja plattformunabhängig zur Verfügung stellen muss.

  • chm: imo aufwendig in der Erstellung
  • HTML: das einfachste, auch Betrachter kann man schnell schreiben aber wie löst man das am besten mit einer Suche?
  • INF: umständlich mit dem Programm erstellen und mitliefern

Vielleicht überseh ich da auch nur etwas.

cu tb
Tipp für PostgreSQL: www.pg-forum.de

Warf
Beiträge: 1908
Registriert: Di 23. Sep 2014, 17:46
OS, Lazarus, FPC: Win10 | Linux
CPU-Target: x86_64

Re: Hilfe für Programme (plattformunabhängig)

Beitrag von Warf »

Ich934 hat geschrieben:
  • chm: imo aufwendig in der Erstellung
  • HTML: das einfachste, auch Betrachter kann man schnell schreiben aber wie löst man das am besten mit einer Suche?
  • INF: umständlich mit dem Programm erstellen und mitliefern

Ich weiß nicht ob ich grad dumm bin, aber sind chm's nicht einfach HTML Seiten die durch nen compiler gejagt/zipper wurden? Ansonsten, CHM und INF würden für mich schonmal komplett wegfallen, weil das Microsoft typen sind, und du auf linux erst sofware nachinstallieren musst damit du sie betrachten kannst.

Grundsätzlich hast du mMn 3 optionen: 1. Plaintext 2. HTML und 3. PDF. Jedes System hat von Haus aus die Möglichkeit diese Dateien zu zeigen.
Plaintext ist sehr simpel, und mMn. oftmals schon ausreichend. Wenn du aber natürlich bilder oder sowas drin haben willst ist das doof. Wenn dus richtig machen willst bleibt also HTML und PDF über. HTML selbst zu schreiben ist viel zu aufwendig (warum du es als die einfachste Alternative siehst ist mir fremd). Du willst wenn möglich auf eine einfachere Markdown Sprache zurückgreifen, welche dann zu HTML übersetzt werden kann. Da du HTML dann einfach zu PDF speichern kannst (und die meisten Markdown Sprachen sowohl PDF als auch HTML übersetzen können) ist die Wahl zwischen HTML und PDF also relativ konsequenzlos, da du die selben Tools für das erstellen von beidem verwenden würdest.

Als Markdown Sprachen zum erstellen der dokumentation würden mir jetzt auf anhieb das klassische Markdown einfallen, das extrem einfach ist, dann das emacsOrgmode (wobei ich da spacemacs mit org layer empfehlen kann), oder wenn du deutlich mehr Möglichkeiten willst (das dafür auch komplexere) LaTeX. Alle samt lassen sich problemlos nach HTML umwandeln und sind um Welten angenehmer als HTML

Ich934
Lazarusforum e. V.
Beiträge: 316
Registriert: So 5. Mai 2019, 16:52
OS, Lazarus, FPC: ArchLinux und Windows mit FPCUPdeluxe (L: 2.0.X, FPC 3.2.0)
CPU-Target: x86_64, i386
Wohnort: Bayreuth

Re: Hilfe für Programme (plattformunabhängig)

Beitrag von Ich934 »

Guten Morgen,

eine Dokumentation zu schreiben mit einem Wiki etc. ist an sich kein Thema. Da ist MD optimal. Auch eine Anleitung mit Latex etc. ist keine große Sache. Mir gehts jetzt aber um die Hilfefunktionen, die direkt aus dem Programm aus aufgerufen werden können.

Aktuell nutze ich hierfür HTML. Ist auch nicht komplizierter als MD und das muss nicht aufwendig sein. Problem ist hier nur die Suchfunktion...

Wie machen das andere? Oder gibt es da keine Hilfe mehr?
Tipp für PostgreSQL: www.pg-forum.de

Benutzeravatar
fliegermichl
Lazarusforum e. V.
Beiträge: 1432
Registriert: Do 9. Jun 2011, 09:42
OS, Lazarus, FPC: Lazarus Fixes FPC Stable
CPU-Target: 32/64Bit
Wohnort: Echzell

Re: Hilfe für Programme (plattformunabhängig)

Beitrag von fliegermichl »

Ich stand vor Jahren vor dem gleichen Problem und hab für mich die Lösung gefunden. Ich hab mir ein eigenes Hilfesystem programmiert, bei dem sogar der Anwender selbst die Hilfe während der Laufzeit ergänzen und z.B. um Suchbegriffe erweitern kann.

Das ganz besteht aus einer Treeförmigen Gruppenstruktur die jeweils weitere Untergruppen und/oder Hilfeseiten beinhalten können. Jeder Hilfeseite ist eine Kontextnummer zugeordnet. Diese wird im Event Application.OnHelp an eine Funktion RunHelp übergeben. Diese durchsucht die Gruppenstruktur nach der übergebenen Kontextnummer und zeigt dann die entsprechende Hilfeseite an.

Die Hilfeseiten selbst können Texte, Bilder und Links auf andere Hilfeseiten beinhalten.

Zu guter letzt kann die gesamte Treestruktur mit den Hilfeseiten ausgedruckt werden und so hat der Anwender auch gleich ein Handbuch.

marcov
Beiträge: 1100
Registriert: Di 5. Aug 2008, 09:37
OS, Lazarus, FPC: Windows ,Linux,FreeBSD,Dos (L trunk FPC trunk)
CPU-Target: 32/64,PPC(+64), ARM
Wohnort: Eindhoven (Niederlande)

Re: Hilfe für Programme (plattformunabhängig)

Beitrag von marcov »

HTML und PDF fallen weg, weil ohne Index und Suchfunctione ist es einfach keine Hilfe aber Online Docs. HTML ist auch ein Mist weil es soviel lose Dateien gibt, und es immer kleine Probleme gibt mit Pfade im HTML.

IM FPC/Lazarus context ist html auch ein Mist weil unterschiedliche HTML doku sich schlecht versionieren und integrieren (cross Pakket links)

Fuer die Arbeit mache Ich heute nur PDF Dokumention mittels Latex(**). Ich habe ein Paar Mal daraus auch HTML erzeugt, und die (wie FPC prog und ref CHMs) mit ein einfache Indexgenerator nach CHM umgesetzt (*)

Wir tun fast nur Windows, und PDF ist immerhin die Hauptdokumentation, die CHM Hilfe nur zusätzlich. Aber für Hilfe auf nicht Windows muss man fast immer was installieren.

Heute liefere ich keine Online hilfe/doku mehr aus, nur die Dokumentation PDF. Die Applikation fuer den es wichtig war ist eingestellt/eingefroren. Aber wenn ich es wieder musste, würde ich ein CHM Webserver machen. Ein app der CHM liest und über eine lokaler http Socket HTML Dateien bereit stellt, und sich dann mit dem normalen Browser nutzen lasst.

(*) der FPC Umsetzer ist originell auf diese Kode basiert
(**) Latex ist sehr stabiel im Zeit. (versioning). Man kann Dokumenten machen die schon bestehende Texte includen, und die eben Konditionell parametrisieren. So teile wir die allgemeinere Teilen der Doku zwischen mehrere Kunden.

Ich934
Lazarusforum e. V.
Beiträge: 316
Registriert: So 5. Mai 2019, 16:52
OS, Lazarus, FPC: ArchLinux und Windows mit FPCUPdeluxe (L: 2.0.X, FPC 3.2.0)
CPU-Target: x86_64, i386
Wohnort: Bayreuth

Re: Hilfe für Programme (plattformunabhängig)

Beitrag von Ich934 »

Viel probiert und jetzt folgende Lösung für mich gefunden:

* Zentrale Web Lösung mit einem Jekyll Server. Pflege von mehreren Personen mit MD Dateien möglich
* Hilfe zeigt darauf
* Theoretisches abziehen der statischen Seiten möglich und bereitstellen einer lokalen Hilfe machbar durch statische HTML Seiten
* Änderung im Programm nur durch umschalten einer Variable in der HTML- Help Komponente machbar
* Suche per JavaScript vorhanden - hier bin ich noch dabei das zu verbessern

Lösung für mich damit optimal.

Schöne Grüße
Tipp für PostgreSQL: www.pg-forum.de

MmVisual
Beiträge: 1445
Registriert: Fr 10. Okt 2008, 23:54
OS, Lazarus, FPC: Winuxarm (L 3.0 FPC 3.2)
CPU-Target: 32/64Bit

Re: Hilfe für Programme (plattformunabhängig)

Beitrag von MmVisual »

Ich schreibe schon seit über 10 Jahren Programme für Windows und Linux und liefer dazu eine Kontextbezogene Hilfe im CHM Format mit.
Ich schreibe die Hilfe als HTML Dateien, und kann diese (als sozusagen zusätzliches Feature) 1:1 online stellen ins Internet.
Mit dem Microsoft CHM File Compiler (recht alt, von 2002) linke ich alle Dateien zusammen in eine CHM Datei.
Dazu gibt es die Dateien:
xxxx.hhp - Html Help Project
xxxx.hhc - Html Help Content, diese ist der linke Baum in der Hilfe-Datei und wird mit dem Microsoft Help File compiller erzeugt
Alis.h - Hier wird einem Alias Name die Reale HTML Datei zugewiesen
Index.h - Hier stehen #defines drin die einem Alisnamen einen Wert zuweisen (die Kontext-Nummer)
Mehr zusätzliche Dateien braucht es nicht.

Unter Windows wird in der regel die Hilfe mit der "hh.exe" gestartet und als Parameter der Dateiname sowie die Kontext Nummer übergeben.
Unter Linux braucht es die Zusätzliche Installation von "KChmViewer", der unterstützt ebenfalls die Kontext Nummer und man kann somit die entsprechende Hilfe Seite öffnen. (Den KChmViewer gibt es auch für Windows und mag ich leiber als das HH Tool von MS)

Nun kann man in der eigenen EXE bei den Steuerelementen die Eigenschaft "Context" mit der gleichen Zahl füllen wie die "Kontext Nummer" in der Hilfe. Drückt man die F1 Taste, so sucht man am dem ActiveControl so lange nach dem Parent Control bis man eine Zahl > 0 in "Context" gefunden hat, somit braucht nicht jedes Steuerelement diese "Context", sondern nur der Reiter oder das Formular. Anschließend startet man die jeweilige EXE mit den Parametern (CHM Datei Order/Name, Kontext Nummer).

Ich finde die Variante der CHM Datei sehr einfach, da man nur diese 4 Dateien hat, (+ die HTML Dateien). Diese Dateien sind zudem alles Textdateien, die man somit perfekt mit z.B. SVN verwalten kann und sehr einfach aufgebaut sind.

Beispiel Datei HHP:

Code: Alles auswählen

[OPTIONS]
;Default Font=Arial,10,0
Compatibility=1.1
Compiled file=XXXX.chm
Contents file=XXXX.hhc
Default topic=Index.htm
Display compile progress=No
Full-text search=Yes
Language=0x407 Deutsch (Deutschland)
Title=EleLa - XXXX - Hilfe
 
 
[FILES]
Index.htm
 
[ALIAS]
#include Alias.h
 
[MAP]
#include Index.h


Beispiel Datei HHC (XML Format):

Code: Alles auswählen

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<OBJECT type="text/site properties">
   <param name="Window Styles" value="0x800025">
</OBJECT>
<UL>
   <LI> <OBJECT type="text/sitemap">
      <param name="Name" value="Inhalt">
      <param name="Local" value="Index.htm">
      </OBJECT>
   <LI> <OBJECT type="text/sitemap">
      <param name="Name" value="Installation">
      <param name="Local" value="Install.htm">
      </OBJECT>
</UL>
</BODY></HTML>
 


Beispiel Datei Alis.h:

Code: Alles auswählen

IDH_Index=Index.htm
IDH_INSTALL=Install.htm


Beispiel Datei Index.h:

Code: Alles auswählen

#define IDH_Index 1
#define IDH_INSTALL 100


Initialisierung:

Code: Alles auswählen

Application.OnHelp := @FOnHelp;
 
function TfrmMain.FOnHelp(Command: word; Data: PtrInt; var CallHelp: boolean): boolean;
begin // Online-Hilfe aufrufen
  btnHelpClick(nil);
  Result := True;
end;
 
procedure TfrmMain.btnHelpClick(Sender: TObject);
var
  iHelpContext: longint;
  Obj: TControl;
  sActivControl: String;
 
  procedure LookControl;
  begin
    while (Obj <> nil) do
    begin
      if Obj.HelpContext > 0 then
      begin
        iHelpContext := Obj.HelpContext;
        Break;
      end
      else Begin
        Obj := Obj.Parent;
        sActivControl := sActivControl + ' > ' + Obj.Name;
      end;
    end;
  end;
 
begin
  iHelpContext := 0;
  sActivControl := '';
  if Screen.ActiveControl <> nil then
  begin // Überprüfung, ob die Hilfe vom Aktuellen Formular gestartet werden kann
    if (Screen.ActiveControl is TControl) then
    begin
      sActivControl := TControl(Screen.ActiveControl).Name;
      Obj := TControl(Screen.ActiveControl);
      if Obj is TPageControl then
        Obj := TControl(TPageControl(Obj).ActivePage);
      LookControl;
    end;
  end;
  if iHelpContext > 0 then
  begin
    If ErrMessagesDebugMode >= 1 Then
      DoLog('ShowHelp: ' + IntToStr(iHelpContext) + ' / ' +sActivControl);
    LaunchCHMHelp(sHilfeDatei, iHelpContext); // aufrufen.
  End Else Begin
    DoLog('E: Cannot open help, ContextID=0! ' + sActivControl);
  end;
end;
 
// Launch an external application
//Adapted from Source: http://wiki.lazarus.freepascal.org/Exec ... l_Programs
procedure LaunchCHMHelp(ChmFileName: string; iID: integer = -1);
var
  AProcess: TProcessUTF8;
{$ifdef WINDOWS}
  s: String;
  Reg: TRegistry;
  bKC: Boolean;
{$endif}
begin
  If Assigned(frmMain) Then
    frmMain.SetSlHilfe(); // HTML Hilfe Dateinamen in slHilfe übertragen. .Object ist der Hilfe-Index
  if not FileExistsUTF8Mm(ChmFileName) then
  begin
    If Assigned(frmMain) Then
      frmMain.DoLog('Cannot Open Helpfile ' + ChmFileName + ' Context ' + IntToStr(iID));
    Exit;
  end;
  if iID < 0 then
    iID := 1; // Hier Default ID Eintragen für Hilfe-Aufruf
{$ifdef WINDOWS}
  s := ExtractFilePath(Application.ExeName) + 'kchmviewer.exe';
  bKC := FileExistsUTF8Mm(s);
  If not bKC Then
  Begin
    Reg := TRegistry.Create;
    Reg.RootKey := HKEY_LOCAL_MACHINE;
    AProcess := TProcessUTF8.Create(nil);
    If Reg.OpenKeyReadOnly('\SOFTWARE\Wow6432Node\Ulduzsoft\KchmViewer') Then
    Begin // KChmViewer gefunden
      s := IncludeTrailingPathDelimiter(Reg.ReadString('')) + 'kchmviewer.exe'; // Nutze KChmViewer unter Windows
      bKC := FileExistsUTF8Mm(s); // EXE auch vorhanden
    end;
    Reg.Free;
  End;
  If bKC Then
  Begin // Nutze KChmViewer unter Windows
    AProcess.Executable := s;
    AProcess.Parameters.Clear;
    AProcess.Parameters.Add('-token');
    AProcess.Parameters.Add('de.mmvisual.elela');
    iID := slHilfe.IndexOfObject(TObject(PtrInt(iID))); // Dateiname aus Hilfe-Index lesen
    If iID >= 0 Then
    Begin
      AProcess.Parameters.Add('-showPage');
      AProcess.Parameters.Add(slHilfe[iID]);
    End;
    AProcess.Parameters.Add(ChmFileName);
    If Assigned(frmMain) Then
      frmMain.DoLog(AProcess.Executable + ' ' + StringReplace(AProcess.Parameters.Text, CRLF, ' ', [rfReplaceAll]));
  End Else Begin // Nutze hh.exe unter Windows
    // Use AProcess to execute the Microsoft HTML Help file in the windows directory
    // The "10" in "-mapid 10 ms-its:" signifies the table of contents
    AProcess.Executable := 'hh.exe';
    AProcess.Parameters.Clear;
    AProcess.Parameters.Add('-mapid');
    AProcess.Parameters.Add(IntToStr(iID));
    AProcess.Parameters.Add('ms-its:' + UTF8ToSys(ChmFileName)); // *DEBUG UTF8
    //  AProcess.CommandLine := 'hh.exe -mapid ' + IntToStr(iID) + ' ms-its:' + UTF8ToSys(ChmFileName); // *DEBUG UTF8
  end;
  AProcess.Execute;
  AProcess.Free;
{$else}
  If FileExistsUTF8Mm('/usr/bin/kchmviewer') Then
  Begin
    iID := slHilfe.IndexOfObject(TObject(PtrInt(iID))); // Dateiname aus Hilfe-Index lesen
    AProcess := TProcessUTF8.Create(nil);
    AProcess.Executable := '/usr/bin/kchmviewer';
    AProcess.Parameters.Clear;
    AProcess.Parameters.Add('-token');
    AProcess.Parameters.Add('de.mmvisual.elela');
    If iID >= 0 Then
    Begin
      AProcess.Parameters.Add('-showPage');
      AProcess.Parameters.Add(slHilfe[iID]);
    End;
    AProcess.Parameters.Add(ChmFileName);
    If Assigned(frmMain) Then
      frmMain.DoLog(AProcess.Executable + ' ' + StringReplace(AProcess.Parameters.Text, LF, ' ', [rfReplaceAll]));
    AProcess.Execute;
    AProcess.Free;
  End Else OpenDocumentMm(ChmFileName);
{$endif}
end;
 
{$ifdef UNIX}
Function OpenURLMm(AURL: String): Boolean;
Begin
  Result := OpenURL(AURL);
end;
{$ELSE}
function OpenURLMm(AURL: String): Boolean;
var
{$IFDEF WinCE}
  Info: SHELLEXECUTEINFO;
{$ELSE}
  PURL: String;
  ws, wsp: WideString;
  ans, ansp: AnsiString;
  IsFileUriWithSpaces: Boolean;
const
  FileURIScheme = 'file://';
{$ENDIF}
begin
  Result := False;
  if AURL = '' then Exit;
  PURL := ExtractFileDir(AURL);
  If PURL = AURL Then PURL := '';
  If Not DirectoryExistsUTF8Mm(PURL) Then PURL := '';
  {$IFDEF WinCE}
  FillChar(Info, SizeOf(Info), 0);
  Info.cbSize := SizeOf(Info);
  Info.fMask := SEE_MASK_FLAG_NO_UI;
  Info.lpVerb := 'open';
  Info.lpFile := PWideChar(UTF8Decode(AURL));
  ToDo:
  Info.lpDir := ....
  Result := ShellExecuteEx(@Info);
  {$ELSE}
  if Win32Platform = VER_PLATFORM_WIN32_NT then
  begin
    //Urls that start with file:// are allowed to contain spaces and should be quoted on NT platform,
    //but on Win9x quoting it fails
    //Since on Windows filenames cannot contain the " character, we need not care about it and simply enclose the AURL
    IsFileUriWithSpaces := (Pos(#32,AURL) > 0) and (CompareText(Copy(AURL,1,Length(FileURIScheme)), FileURIScheme) = 0);
    if IsFileUriWithSpaces then AURL := '"' + AURL + '"';
    ws := UTF8Decode(AURL);
 
    if PURL <> '' Then
    Begin
      IsFileUriWithSpaces := (Pos(#32,PURL) > 0) and (CompareText(Copy(PURL,1,Length(FileURIScheme)), FileURIScheme) = 0);
      if IsFileUriWithSpaces then PURL := '"' + PURL + '"';
      wsp := UTF8Decode(PURL);
    end Else wsp := '';
    Result := ShellExecuteW(0, nil, PWideChar(ws), nil, PWideChar(wsp), SW_SHOWNORMAL) > 32;
  end
  else
  begin
    ans := Utf8ToAnsi(AURL); // utf8 must be converted to Windows Ansi-codepage
    ansp := Utf8ToAnsi(PURL);
    Result := ShellExecute(0, nil, PAnsiChar(ans), nil, PAnsiChar(ansp), SW_SHOWNORMAL) > 32;
  end;
  {$ENDIF}
end;
{$ENDIF}
 
// Open a document with the default application associated with it in the system
{$ifdef UNIX}
Function OpenDocumentMm(APath: String): Boolean;
Begin
  Result := OpenDocument(APath);
end;
{$ELSE}
function OpenDocumentMm(APath: String): Boolean;
begin
  Result := OpenURLMm(APath);
end;
{$ENDIF}


Das "DoLog()" kannst Du löschen.

Nun wird ein Steuerelement mit "Context:=100" angelegt, der Focus ist da drauf, drücken auf die F1 Taste öffnet die Hilfe mit der Datei "Install.htm".
Sollte ich noch irgend ein Stück Code "vergessen" zu kopieren haben, dann einfach das xxxxxMM zu xxxxx (ohne MM im Funktionsname) ersetzen, dann sollte es gehen. (z.B. "OpenDocumentMm()" >> "OpenDocument()")
EleLa - Elektronik Lagerverwaltung - www.elela.de

Antworten